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Certification and Warranty 
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Features 



The 8086/186 C Cross Compiler translates C source code into 8086/186 
assembly language which can be accepted by the HP B1449 assembler. This 
compiler has special features to help meet the needs of the embedded system 
designer: 

• ANSI standard C compiler and preprocessor. 

• Standard command line interface for compatibility with make and other 
utilities. 

• Complete C support and math libraries from ANSI standard for 
nonhosted environments. 

• In-line code generation and libraries to support the 8087 floating point 
coprocessor. 

• Three ways to embed assembly language in C source. 

• Named section specification in C source. 

• Choice of small or large memory model for function calls and static data 
access. 

• Option to copy initial value data from ROM to RAM at load time. 

• Listings with generated assembly language, C source, and cross references. 

• Fully reentrant generated code. 

• Optimization for either time or space. 

• Constant folding, automatic register variable selection, and other global 
optimizations. 

• Full symbol information and C source line numbers provided for 
debugging, emulation, simulation, and analysis tools. 

• Compiler reliability ensured through object-oriented design and 
exhaustive testing. 
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Getting Started 

How to get started using the compiler. 
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Chapter 1 : Getting Started 

In this chapter 

This chapter contains the following information: 

• An overview of the 8086/186 C compiler. 

• Instructions for common tasks, such as compiling a simple program. 

• Short examples so you can practice the common tasks. 

What you need to know 

Before you begin to learn how to use this compiler, you should be familiar 
with the following: 

• The C programming language. 

• The Intel 8086 microprocessor architecture. 

• Basic host operating system commands (such as cp, mv, Is, mkdir, rm, and 
cd) and a text editor (such as vi). 

In addition, most sections in this manual assume that you are familiar with 
8086/186 assembly language. 
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Parts of the compiler 

The "compiler" is really a set of programs: 

• cc8086, the C compilation control command. 

• cpp8086, the C preprocessor. 

• clst8086, the lister. 

• ccom8086, the C compiler. 

• opt8086, the peephole optimizer. 

The compiler makes use of several assembler programs: 

• ap86, the assembler preprocessor. 

• as86, the assembler. 

• ld86, the linking loader. 

To compile a C program, you can use just the cc8086 C compilation control 
command. The cc8086 command will run the other programs as needed. 
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Summary of compiler options 



-b Invoke Basis Branch Analyzer preprocessor. 

-c Do not link programs (object files are generated). 

-C Do not strip C-style comments in preprocessor. 

-d Separate data into initialized and uninitialized 

segments. 

-D name[= def] Define name to the preprocessor. 

-e Fast error checking (no code is generated). 

-E Preprocess only (send result to standard output). 

-f Generate code to use the 8087 coprocessor. 

-g Generate run-time error checking code (overrides -O). 

-h Generate HP 64000 format (.X) files. 

-I dir Change include file search algorithm. 

-k linkcomfile Link using the linkcomfile linker command file. 

-K Enforce strict segment consistency. 

-Ix Search libx.a when linking. 

-L[i][x] Generate ".O" listing(s). The -i option causes include 

files to be expanded and included in the listing. The -x 
option causes cross-reference tables to be included in 
the listings. (Overridden by-e, -E, and -P.) 

-m memoryModel Specify memory model, small, compact, medium, or 
large. 
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Summary of compiler options 



-M Cause generation of more warning messages than are 

generated by default. 

-n Cause static functions in the large memory model to be 

called "NEAR". 

-N Cause linking with linkcom.k (no I/O) rather than 

iolinkcom.k. 

-o outfile Name absolute file outfile instead of a.out.x. 

-0[G] [T] Optimize. -O for space, -OT for time, -OG for 

debugging. 

-p processor Compile code for the specified processor. 

-P Preprocess only (send result to .i files). 

-Q Byte align data in memory instead of default word 

alignment. 

-r dir Use default linker command file in /usr/hp64000/env/iiiV 

instead of the default. 

-s Strip symbol table information (overridden by -g and 
-L). 

-S Only generate assembly source files (with .s extensions). 

-t c,name Insert subprocess c whose full path is name. 

-u Consider non-constant static data uninitialized. 

-U name Undefine name to the preprocessor. 

-v Verbose (produce step-by-step description on stderr). 

-w Suppress warning messages. 

-W c,args Pass args as parameters to subprocess c. 
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Summary of file extensions 



.a Library (archive) files. 

.A HP format assembler symbol file. 

.c C source files. 

.EA, .EB Emulator configuration files. 

.h Include (header) files. 

.i "Preprocess only" output (generated with the -P option). 

.k Linker command file. 

.L HP format linker symbol file. 

.o Relocatable object file. 

.O Listing files (generated with the -L option). 

.s Assembly language source file. 

.x HP-OMF 86 absolute (executable) file. 

.X HP format absolute (executable) file. (Generated with 
the -h option.) 

.Ys Symbol file directory. 
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To install the software 

1 Load the software from the software media. 

Instructions for installing the software are provided with the software media, 
or in your operating system's system administration guide. 

2 Set the HP64000 environment variable. 

Set this variable to the location of the software, usually /usr/hp64000. 

3 Set the MANPATH environment variable. 

Add $HP64000/man to this variable so that you can read the on-line "man 
pages." 

4 Set the PATH environment variable. 

Add $HP64000/bin to your path so that you can run the compiler programs. 

You should add these commands to your .login, .vueprofile, or .profile file (if 
they are not there already) so that you won't need to re-enter them every time 
you log in. 



Examples If you installed the compiler in the root directory on an HP-UX system, enter: 

export HP64000=/usr/hp64000 
export PATH=$PATH : $HP64000/bin 
export MANPATH=$MANPATH : $HP64000/man 

On a Sun system, you would enter: 

setenv HP64000 /usr/hp64000 
setenv PATH $PATH : $HP64000/bin 
setenv MANPATH $MANPATH : $HP64000/man 
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To create a simple C program 



• Use a text editor to create the file simplex: 



main ( ) 
{ 

char str [ 80 ] ; 

printf ( "Enter string: "); 
gets (str) ; 

printf (" \nYou entered: \"%s\"\n", str); 



Figure 1-1. The "simple.c" Example Program 
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To compile a simple program 

• Use the cc8086 comand at your host operating system prompt. 



Example To compile the "simplex" example program, enter the following command: 

cc8086 simple. c 

This command generates the executable file a.out.x by default. The compiler 
will print a warning message because a target processor was not specified. 
Because this is just an example, ignore the warning. 
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To generate an assembly listing 

• Use the -L compiler option. 

This option generates a listing of the C source, which includes the generated 
assembly code, and a linker listing. 



Example To generate the listings for "simplex", enter: 

cc8086 -L simple. c 

The mixed source and assembly listing is sent to file simple.O, and a linker 
listing is sent to file a.out.O. 

Examine the simple.O file and note how: 

• Addresses of strings are passed as parameters to the "_printf ' support 
library routine (Stringl+ 0 is pushed, then _printf is called). 

• String literals are placed in the "const" section. 

Now look at a.out.O and note that: 

• The file shows the default linker command (generated by the compilation 
control command). 

• The linker command is followed by the contents of the default linker 
command file. The default linker command file loads some libraries and 
an emulation monitor or monitor stub. 

• Modules are listed in the order they are loaded. Modules within library 
files are listed in alphabetical order. 

• The module crtO is the program setup routine. Program execution will 
begin with this routine. 
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To select a memory model 

The 8086/186 C compiler allows you to select one of four available memory 
models: large, medium, compact, or small. The compiler defaults to the large 
memory model (option -m large). 

Large Model 

The large memory model allows your code and data to be broken up into many 
named segments of your own choosing. These segments can be located 
anywhere in memory at link time, independent of each other. Segments 
containing "constant" data maybe located next to code segments to facilitate 
putting code and data constants in ROM. In fact, "constant" data maybe 
placed in the same segment as code. Segments may also be "ORGed" to 
absolute physical memory locations through the use of the # pragma 
SEGMENT directive. The efficiency of the compiler in calling functions and 
accessing data is controllable through the use of # pragma SEGMENT and 
# pragma DS directives and the -n option. 

Small Model 

The small memory model produces more compact code than the large memory 
model. The small memory model places all code in a single, pre-defined, 
physical segment and places all data, stack, heap, and constants into a second, 
pre-defined physical segment. Code in the first segment is accessed 
"segment-relative,", but all data in the second physical segment is accessed 
"group-relative" because the pre-defined segments that are combined to form 
the second physical segment are part of a group named data_const. Because 
the small memory model uses just two physical segments, code is limited to 
64K bytes and data, stack, heap, and constants together are limited to 64K 
bytes. 

The # pragma SEGMENT directive and the # pragma DS directive cannot be 
used with the small memory model and are therefore warned at and ignored if 
they are encountered. Also, small memory model does not support "ORGing" 
a segment because this conflicts with the "rules" of small memory model. 
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To select a memory model 



Note It is possible to place constant data in ROM when using the small memory 

model if the embedded environment has RAM near the ROM and both RAM 
and ROM can be addressed within the 64K limit required for group-relative 
accesses. If the embedded system cannot meet these requirements, then the 
constant data must be placed in RAM and initialized at either load-time or at 
run-time (depending upon the embedded environment). 



Medium Model 

The medium memory model has one or more code segments, like the large 
memory model, and one data segment. 

Compact Model 

The compact memory model has one or more data segments, like the large 
model, and one code segment. 

An Example Using Large Memory Model 

The compiler generates code to load the DS register with the paragraph 
number of the currently active static data segment (providing any such 
accesses are made in the function) at the beginning of each function. 
Thereafter, accesses to items in the data segment are performed DS-relative 
and all other accesses are performed ES-relative; which is far more expensive 
since ES must, potentially, be reloaded prior to each access. Thus, care should 
be taken to have the most appropriate data segment active at function 
definition (using the # pragma SEGMENT and # pragma DS directives). 

Auto variables and parameters are accessed SS-relative since they are on the 
stack and therefore located in the userstack segment. 

The example program demonstrates how the compiler selects the segment 
with which to perform DS-relative accesses. When largemodel.c is compiled 
using the following command line, the largemodel.O listing file results. 

$ CC8086 -SOL largemodel.c <RETURN> 
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♦pragma SEGMENT DATA=my_datal 
int il; 

♦pragma SEGMENT PROG=my_prog2 DATA=my_data2 

int i2; /* This is in the "active" static data segment. */ 

void function () 
{ 

il += i2; /* i2 is in "active" static data segment. */ 

} 

♦pragma SEGMENT PROG=my_progl 

main ( ) 

{ 

long al; /* al is a dynamic variable on the stack. */ 

al = 1; /* Accessed SS-relative. */ 

il++; /* Accessed DS-relative. */ 

i2++; /* Accessed ES-relative. */ 
function ( ) ; 



Figure 1-2. largemodel.c 
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HPB1493-19303 8086 C Cross Compiler A. 04. 01 largemodel . c 

MKT:@(#) B1493-19303 A. 04. 01 8086 C CROSS COMPILER 03May95 
Memory Model: large 

$PAGEWIDTH (230) 
$NOPAGING 

NAME "largemodel" 
%DEFINE (MM_CHECK_) (MM_CHECK_L) 
%DEFINE (lib) (lib) 
%DEFINE (SS) (SS) 
%DEFINE (DS) (DS) 
%DEFINE (ALIGN) (WORD) 
%DEFINE (DALIGN) (WORD) 

my_prog2 SEGMENT %ALIGN PUBLIC 'CODE' 

%DEFINE (CodeSegment ) (my_prog2) 

1 #pragma SEGMENT DATA=my_datal 

2 int il; 

3 Ipragma SEGMENT PROG=my_prog2 DATA=my_data2 

4 int i2; /* This is in the "active" static data segment. */ 
5 

6 void function () 
1 { 

PUBLIC _function 

ASSUME CS : % Code Segment , DS : my_data2 
_function PROC FAR 

%SET (SAVE_ALL_NPX, 2) 

PUSH DS 

MOV AX,my_data2 

MOV DS,AX 

8 il += i2; /* i2 is in "active" static data segment. */ 
MOV DX, SEG _il 

MOV DI, OFFSET _il+0 

MOV AX,%DS:WORD PTR _i2[0] 

MOV ES,DX 

ADD ES:WORD PTR [DI],AX 

9 } 

f unctionExitl : 

POP DS 
returnLabell : 

RET 

_function ENDP 
my_prog2 ENDS 

my_progl SEGMENT %ALIGN PUBLIC 'CODE' 

%DEFINE (CodeSegment ) (my_progl) 
10 

11 (pragma SEGMENT PROG=my_progl 

12 main ( ) 

13 ( 

PUBLIC _main 

ASSUME CS : % Code Segment , DS : my_data2 
_main PROC FAR 
%SET (SAVE_ALL_NPX, 2) 

PUSH BP 

MOV BP,SP 



Figure 1-3. largemodel. O 
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SUB 
PUSH 
MOV 
MOV 

%SET (S_al,-4) 

14 long al 



SP, 4 
DS 

AX, my_data2 
DS, AX 



/* al is a dynamic variable on the stack. */ 



15 
16 



17 



al = 1; /* Accessed SS-relative. */ 

MOV SS:WORD PTR [BP+%S_al+0 ] , 1 

MOV SS:WORD PTR [BP+%S_al+0+2 ] , 0 

il++; /* Accessed DSl-relative . */ 

MOV DX, SEG _il 

MOV DI, OFFSET _il+0 

MOV ES,DX 
INC ES:WORD PTR [DI] 

i2++; /* Accessed DSO-relative . */ 

INC %DS:WORD PTR _i2[0] 

function ( ) ; 
CALL FAR PTR _function 



20 } 
f unctionExit2 : 
POP 
MOV 
POP 

returnLabel2 : 
RET 

_main ENDP 
my_progl 
my_dat a 1 

PUBLIC 
EVEN 
_il LABEL 
DB 

my_datal 
my_data2 

PUBLIC 
EVEN 
_i2 LABEL 
DB 

my_data2 

EXTRN 

mm_check 

DW 

mm_check 

END 



DS 

SP, BP 

BP 



ENDS 

SEGMENT %DALIGN PUBLIC 
_il 

BYTE 

2 DUP (0) 

ENDS 

SEGMENT %DALIGN PUBLIC 
_i2 

BYTE 

2 DUP (0) 

ENDS 

%MM_CHECK_: BYTE 
SEGMENT BYTE COMMON 
OFFSET %MM_CHECK_ 
ENDS 



Figure 1-3. largemodel.O (continued) 
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An Example Using Small Memory Model 

Notice that the difference between the source file for large model and the 
source file for small model is the absence of the # pragma SEGMENT 
directives. The # pragma SEGMENT directive and the # pragma DS directive 
are not valid for small model. If they appear, they are warned and ignored. 

All functions are called "NEAR" and are accessed CS-relative. Data, stack, 
heap, and constants all become part of the data_const group and are accessed 
group-relative. The DS, ES, and SS registers are loaded with the same value, 
the data_const paragraph number, by the program startup routine (crtO.o). 

The smallmodel.O listing shows some of the pre-defined segments that make 
up the data_const group. (Segments heap and userstack are added to the 
group at link time.) Through the use of an ASSUME statement, the DS 
register is associated with the group base of data_const instead of a segment 
base value. For this reason, all DS-relative accesses to data are 
group-name-relative instead of segment-name-relative. 



int il; 
int i2; 



/* Will be put in segment "data 
/* Will be put in segment "data". */ 



void function () 



/* Will be put in segment "prog/CODE" */ 
/* (segment "prog" is in class "CODE").*/ 



il + 



= i2; 



main ( ) 



long al; 



/* Will be put in segment "prog/CODE". */ 
/* al is a dynamic variable on the stack. */ 



al = 1; 

11 + + ; 

12 + + ; 

function ( ) ; 



Figure 1-4. smallmodel.c 
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When smallmodel.c is compiled using the following command line, the 
smallmodel.O listing file results. 

$ cc8086 -SOL -m small smallmodel.c <RETURN> 



HPB1493-19303 8086 C Cross Compiler A. 04. 01 smallmodel.c 

MKT:@(#) B1493-19303 A. 04. 01 8086 C CROSS COMPILER 03May95 
Memory Model: small 

$PAGEWIDTH (230) 
$NOPAGING 

NAME "smallmodel" 
%DEFINE (MM_CHECK_) (MM_CHECK_S) 
%DEFINE (SS) (DS) 
%DEFINE(DS) (data_const) 
%DEFINE(GRP) (data_const) 
%GRP GROUP data, idata, udata, const 
data SEGMENT WORD PUBLIC 
data ENDS 

idata SEGMENT WORD PUBLIC 
idata ENDS 

udata SEGMENT WORD PUBLIC 
udata ENDS 

const SEGMENT WORD PUBLIC 
const ENDS 

prog SEGMENT BYTE PUBLIC 'CODE' 

1 int il; /* Will be put in segment "data". */ 

2 int i2; /* Will be put in segment "data". */ 

3 

4 void function () 

5 { /* Will be put in segment "prog/CODE" */ 
PUBLIC _function 

ASSUME CS:prog,DS:%GRP 
_function PROC NEAR 

%SET (SAVE_ALL_NPX, 2) 

6 /* (segment "prog" is in class "CODE").*/ 

7 il += i2; 

MOV AX,%DS:WORD PTR _i2[0] 

ADD %DS:WORD PTR _il[0],AX 

8 } 

f unctionExitl : 
returnLabell : 
RET 

_function ENDP 
9 

1 0 main ( ) 

11 { /* Will be put in segment "prog/CODE". */ 
PUBLIC _main 

ASSUME CS:prog,DS:%GRP 
_main PROC NEAR 
%SET (SAVE_ALL_NPX, 2) 

PUSH BP 

MOV BP,SP 



Figure 1-5. smallmodel.O 
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SUB SP,4 
%SET (S_al, -4) 

12 long al; 

13 

14 al = 1; 

MOV SS:WORD PTR [BP+%S_al+0 ] , 1 

MOV SS:WORD PTR [BP+%S_al+0+2 ] , 0 

il++; 

INC %DS:WORD PTR _il[0] 

i2 + + ; 

INC %DS:WORD PTR _i2[0] 

function ( ) ; 
CALL NEAR PTR _function 



/* al is a dynamic variable on the stack. 



15 

16 
17 



} 



f unctionExit2 : 
MOV 
POP 

returnLabel2 : 
RET 



SP, BP 

BP 



__main 

prog 

data 



_il 

_i2 
data 
mm_check 
mm_check 



ENDP 
ENDS 

SEGMENT WORD PUBLIC 
PUBLIC _il 
EVEN 
LABEL 
DB 

PUBLIC 
EVEN 
LABEL 
DB 
ENDS 
EXTRN 



DW 



BYTE 
2 DUP (0) 
_i2 

BYTE 
2 DUP (0) 

%MM_CHECK_: BYTE 
SEGMENT BYTE COMMON 
OFFSET %MM_CHECK_ 
ENDS 



END 



Figure 1-5. smallmodel.O (continued) 
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An Example Using Compact Memory Model 

All functions are called "FAR." Data, stack, heap, and constants all become 
part of the data_const group and are accessed group-releative just as with the 
small memory model. 

Through the use of an ASSUME statement, the DS register is associated with 
the group base of data_const instead of a segment base value. For this reason, 
all DS-relative accesses to data are group-name-relative instead of 
segment-name-relative. 



tpragma SEGMENT DATA=my_datal 
int il; 

fpragma SEGMENT PR0G=my_prog2 DATA=my_data2 

int i2; /* This is in the "active" static data segment. */ 

void function ( ) 
{ 

il += i2; /* i2 is in "active" static data segment. */ 

} 

#pragma SEGMENT DATA=my_progl 
main ( ) 

( 

long al; /* al is a dynamic variable on the stack. */ 

al = 1; /* Accessed SS-relative. */ 

il++; /* Accessed DS-relative. */ 

i2++; /* Accessed DS-relative. */ 
function ( ) ; 



Figure 1-6. compactmodel.c 



When compactmodel.c is compiled using the following command line, the 
compactmodel.O listing file results. 

S cc8086 -SOLm compact compactmodel.c <RETURN> 
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HPB1493-19303 8086 C CROSS COMPILER A. 04. 01 compactmodel . c 



;MKT:@(#) B1493-19303 A. 04. 01 8086 C CROSS COMPILER 



03May95 



; Memory Model : compact 

$PAGEWIDTH (230) 
$NOPAGING 

NAME "compactmodel" 
%DEFINE (MM_CHECK_) (MM_CHECK_C) 
%DEFINE (SS) (SS) 
%DEFINE (DS) (DS) 
%DEFINE (ALIGN) (WORD) 
%DEFINE (DALIGN) (WORD) 

my_prog2 SEGMENT %ALIGN PUBLIC 'CODE' 

%DEFINE (CodeSegment ) (my_prog2) 

1 #pragma SEGMENT DATA=my_datal 
int il; 

tpragma SEGMENT PROG=my_prog2 DATA=my_data2 

int i2; /* This is in the "active" static data segment. */ 



void function ( ) 
{ 

PUBLIC _function 

ASSUME CS:prog,DS:my_data2 
_function PROC NEAR 

%SET (SAVE_ALL_NPX, 2) 

PUSH DS 

MOV AX,my_data2 

MOV DS,AX 

8 il += i2; /* i2 is in "active" static data segment. */ 

MOV DX, SEG _il 

MOV DI, OFFSET _il+0 

MOV AX,%DS:WORD PTR _i2[0] 

MOV ES,DX 

ADD ES:WORD PTR [DI],AX 



functionExitl : 

POP DS 
returnLabell : 

RET 

_function ENDP 
10 

11 tpragma SEGMENT DATA=my_progl 

12 main ( ) 

13 { 



PUBLIC 
ASSUME 

_main PROC 

%SET (SAVE_ALL_NPX, 2) 
PUSH BP 
MOV BP,SP 
SUB SP,4 

%SET (S_al,-4) 

14 long al; 

15 



_main 

CS: prog, DS: NOTHING 
NEAR 



/* al is a dynamic variable on the stack. */ 



Figure 1-7. compactmodel.O 
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16 al = 1; /* Accessed SS-relative. */ 
MOV SS:WORD PTR [BP+%S_al+0 ] , 1 

MOV SS:WORD PTR [BP+%S_al+0+2 ] , 0 

17 il++; /* Accessed DS-relative. */ 
MOV DX, SEG _il 

MOV DI, OFFSET _il+0 

MOV ES,DX 

INC ES:WORD PTR [DI] 

18 i2++; /* Accessed DS-relative. */ 
MOV DX, SEG _i2 

MOV DI, OFFSET _i2+0 

MOV ES,DX 

INC ES:WORD PTR [DI] 

19 function ( ) ; 

CALL NEAR PTR _function 



20 } 
f unctionExit2 : 
MOV 
POP 

returnLabel2 : 
RET 

_main ENDP 

my_prog2 

my_datal 

PUBLIC 
EVEN 
_il LABEL 
DB 

my_dat a 1 
my_data2 

PUBLIC 
EVEN 
_i2 LABEL 
DB 

my_data2 

EXTRN 

mm_check 

DW 

mm_check 

END 



SP, BP 
BP 



ENDS 

SEGMENT %DALIGN PUBLIC 
_il 

BYTE 

2 DUP (0) 

ENDS 

SEGMENT %DALIGN PUBLIC 
_i2 

BYTE 

2 DUP (0) 

ENDS 

%MM_CHECK_: BYTE 
SEGMENT BYTE COMMON 
OFFSET %MM_CHECK_ 
ENDS 



Figure 1-7. compactmodel.O (continued) 
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An Example Using Medium Memory Model 

All functions are called "NEAR" and are accessed CS-relative. 

The ES, DS, and SS registers are loaded with the same value, the data_const 
paragraph number, by the program startup routine crtO.o, just as with the 
small memory model. 



♦pragma SEGMENT DATA=my_datal 
int il; 

♦pragma SEGMENT PROG=my_prog2 DATA=my_data2 

int i2; /* This is in the "active" static data segment. */ 

void function)) 
{ 

il += i2; /* i2 is in "active" static data segment. */ 

} 

♦pragma SEGMENT DATA=my_progl 

main ( ) 

{ 

long al; /* al is a dynamic variable on the stack. */ 

al = 1; 

11 + + ; 

12 + + ; 

function ( ) ; 



Figure 1-8. mediummodel.c 



When mediummodel.c is compiled using the following command line, the 
mediummodel.O listing file results. 

$ cc808 6 -SOLm medium mediummodel.c <RETURN> 
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HPB1493-19303 8086 C CROSS COMPILER A. 04. 01 mediummodel . c 

;MKT:@(#) B1493-19303 A. 04. 01 8086 C CROSS COMPILER 03May95 

; Memory Model: medium 

$PAGEWIDTH (230) 
$NOPAGING 

NAME "mediummodel" 
%DEFINE (MM_CHECK_) (MM_CHECK_M) 
%DEFINE (lib) (lib) 
%DEFINE (SS) (DS) 
%DEFINE(DS) (data_const) 
%DEFINE (GRP ) (data_const) 
%DEFINE (ALIGN) (WORD) 
%DEFINE (DALIGN) (WORD) 

%GRP GROUP data, idata, udata, const 
data SEGMENT WORD PUBLIC 
data ENDS 

idata SEGMENT WORD PUBLIC 
idata ENDS 

udata SEGMENT WORD PUBLIC 
udata ENDS 

const SEGMENT WORD PUBLIC 
const ENDS 

my_prog2 SEGMENT %ALIGN PUBLIC 'CODE' 

%DEFINE (CodeSegment ) (my_prog2) 

1 Ipragma SEGMENT DATA=my_datal 

2 int il; 

3 Ipragma SEGMENT PROG=my_prog2 DATA=my_data2 

4 int i2; /* This is in the "active" static data segment. */ 
5 

6 void function () 
1 { 

PUBLIC _function 
ASSUME CS : % Code Segment , DS : %GRP 
_function PROC FAR 

%SET (SAVE_ALL_NPX, 2) 

8 il += i2; /* i2 is in "active" static data segment. */ 
MOV AX,%DS:WORD PTR _i2[0] 

ADD %DS:WORD PTR _il[0],AX 

9 } 

f unctionExitl : 
returnLabell : 
RET 

_function ENDP 
10 

11 Ipragma SEGMENT DATA=my_progl 

12 main() 

13 { 

PUBLIC _main 

ASSUME CS : % Code Segment , DS : %GRP 
_main PROC FAR 
%SET (SAVE_ALL_NPX, 2) 

PUSH BP 

MOV BP,SP 



Figure 1-9. mediummodel. O 



23 



Chapter 1 : Getting Started 

To select a memory model 



SUB 

%SET (S_al, -4) 
14 
15 

16 



SP, 4 
long al; 
1; 



/* al is a dynamic variable on the stack. */ 



al 

MOV SS:WORD PTR [BP+%S_al+0 ] , 1 

MOV SS:WORD PTR [BP+%S_al+0+2 ] , 0 

17 il++; 

INC %DS:WORD PTR _il[0] 

18 i2++; 

INC %DS:WORD PTR _i2[0] 

19 function ( ) ; 

CALL FAR PTR _function 

20 } 



f unctionExit2 : 
MOV 
POP 

returnLabel2 : 
RET 

_main ENDP 
my_prog2 
my_dat a 1 

PUBLIC 
EVEN 
_il LABEL 
DB 

my_datal 
my_data2 

PUBLIC 
EVEN 
_i2 LABEL 
DB 

my_data2 

EXTRN 

mm_check 

DW 

mm_check 

END 



SP, BP 
BP 



ENDS 

SEGMENT %DALIGN PUBLIC 
_il 

BYTE 

2 DUP (0) 

ENDS 

SEGMENT %DALIGN PUBLIC 
_i2 

BYTE 

2 DUP (0) 

ENDS 

%MM_CHECK_: BYTE 
SEGMENT BYTE COMMON 
OFFSET %MM_CHECK_ 
ENDS 



Figure 1-9. mediummodel.O (continued 
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Calling Run-Time and Support Libraries 

Run-time library routines are called implicitly by the generated assembly code. 
For example, with large and medium memory model, ADD_F32A_LM, 
ADD_F32B_L, or ADD_F32C_L would be called to add two floats. Which of 
the three routines the compiler actually uses depends on where the arguments 
are found and how the code is being optimized. For the small adn compact 
memory model ADD_F32A_SC, ADD_F32B_S, or ADD_F32C_S would be 
called. Note that the names are different between memory models to 
guarantee that the correct run-time library is used. 

Since these implicitly called routines are not visible in the C source, a special 
segment named lib is reserved and understood by the compiler to be the 
segment in which the run-time library is defined, (lib is replaced with prog for 
the small and compact memory model). 

Support library routines, unlike run-time library routines, are called explicitly 
in the C source. Thus, they behave just as though they were user-written 
functions. For the large and medium memory model, their segment names are 
the same as the base name of the library (e.g., libc.a's segment is libc). For the 
small and compact model, the segment name is prog, the same as with 
user-written code. 

The libcalls.c listing shows the calling of run-time library routines and the 
calling of a support library routine. Note that it is important to use # include 
< stdio.h> since without it the compiler does not know that printf() is in 
named segment libc. When libcalls.c is compiled using the following command 
line, the libcalls.O listing file results. 

$ cc8086 -SOL libcalls.c 



♦include <stdio.h> 
main ( ) 

{ 

float f = 1.0; 
float g = 1.0; 

printf("Sum is %f\n", f+g) ; 



Figure 1-10. libcalls.c 
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HPB1493-19303 8086 C Cross Compiler A. 04. 01 libcalls.c 

MKT:@(#) B1493-19303 A. 04. 01 8086 C CROSS COMPILER 03May95 
Memory Model: large 

$PAGEWIDTH (230) 
$NOPAGING 

NAME "libcalls" 
%DEFINE (MM_CHECK_) (MM_CHECK_L) 
%DEFINE (lib) (lib) 
%DEFINE (SS) (SS) 
%DEFINE (DS) (DS) 
%DEFINE (ALIGN) (WORD) 
%DEFINE (DALIGN) (WORD) 

prog_libcalls SEGMENT %ALIGN PUBLIC 'CODE' 
%DEFINE (CodeSegment ) (prog_libcalls ) 

1 #include <stdio.h> 

2 main ( ) 

3 { 



PUBLIC 


_main 










ASSUME 


CS : %Code Segment , DS 


NOTHING 




_main PROC 


FAR 










%SET (SAVE_ALL_NPX, 2) 










PUSH 


BP 










MOV 


BP, SP 










SUB 


SP, 8 










%SET (S_f , -8) 












MOV 


S S : WORD 


PTR 


[BP + %S_ 


f+0] , 00H 




MOV 


SS:WORD 


PTR 


[BP + %S_ 


_f+0+2] , 03FJ 


S0H 


%SET (S_g, -4) 












MOV 


SS:WORD 


PTR 


[BP + %S_ 


g+0] , 00H 




MOV 


SS:WORD 


PTR 


[BP + %S_ 


_g+0 + 2] , 03FJ 


S0H 


4 float 


f = 1.0 










5 float 


g = 1.0 











6 

7 printf("Sum is %f\n", f + g) ; 

LES DI,SS: DWORD PTR [BP+%S_f+0] 

PUSH ES 

PUSH DI 

LES DI,SS:DWORD PTR [BP+%S_g+0] 

PUSH ES 

PUSH DI 

%lib SEGMENT WORD PUBLIC 'CODE' 

EXTRN ADD_F32A_LM : FAR 
%lib ENDS 

CALL FAR PTR AD D_F 3 2 A_LM 

POP AX 

POP DX 

SUB SP,8 

%lib SEGMENT WORD PUBLIC 'CODE' 

EXTRN F32_TO_F64_LM:FAR 
%lib ENDS 

CALL FAR PTR F32_TO_F64_LM 

MOV DX,SEG Stringl 

MOV AX, OFFSET Stringl+0 



Figure 1-11. libcalls. O 
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PUSH DX 

PUSH AX 

CALL FAR PTR _printf 

ADD SP,12 



functionExitl : 
MOV 
POP 

returnLabell : 
RET 

_main ENDP 
prog_libcalls 

EXTRN 
const SEGMENT 
Stringl LABEL 

DB 

DB 

DB 

DB 

DB 

const ENDS 
EXTRN 



mm_check 



DW 



mm_check 



SP, BP 
BP 



ENDS 

_printf : FAR 
%DALIGN PUBLIC 
BYTE 

' Sum is ' 

37 

' f ' 

10 
0 

%MM_CHECK_: BYTE 
SEGMENT BYTE COMMON 
OFFSET %MM_CHECK_ 
ENDS 



END 



Figure 1-11. libcalls.O (continued) 
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To specify the target microprocessor 

• Use the appropriate compiler command: 

• cc8086 for the 8086 

• cc80186 for the 80186 
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To compile for a debugger 

To gain the most benefit from HP debuggers and emulators, follow these 
guidelines: 

• Use the -OG option to generate debugging information. 

• Avoid optimizing modes (-O or -OT). 

• Turn off the automatic creation of register variables (-Wc,-F). 

• Do not use the -h option. HP debuggers now use .x rather than .X files. 

• Use the C compiler's floatingpoint library routines to generate code that 
will run interchangeably in both the debugger/simulator and the 
debugger/emulator. 

• Use the same environment files as you would use to compile for an HP 
64700-series emulator. 



Example To compile the simplex program to be run in a debugger, use the following 

command: 

cc8086 simple. c -LM -OG simple. c 

See Also See the User's Guide for your debugger/emulator, debugger/simulator, or 

emulator interface for information on how to run a program in the debugger 
or emulator environment. 
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To use a makefile 



The make command can simplify the process of compiling your programs. This 
command allows you to specify which files are dependent on which other files 
(for example, make "knows" that files which end in .o are produced by 
compiling corresponding files that end in .c or by assembling programs that 
end in .s). If your host operating system is HP-UX, see the man page for make 
in section 1 of the HP-UX Reference Manual. See also "Make, a Program for 
Maintaining Computer Programs" in the "Programming Environment" volume 
of HP-UX Concepts and Tutorials. 

Because cc8086 is similar to the host cc command, it is easy to tell make how 
to compile, assemble, and link using cross tools. To any makefile designed for 
the host, you need to add some definitions and set up some options. These are: 

CC=/usr/hp64 000/bin/cc80 8 6 
AS=/usr/hp64 000/bin/as8 6 
LD=/usr/hp64 000/bin/ld8 6 

These definitions will cause make's 'built-in" rules to access the cross tools, 
and because the built-in options mean the same thing to the cross tools as they 
do to the host tools, the built-in rules now work when invoking the cross tools. 

Assembling a .s file produced by the cc8086 compiler requires that two 
programs be executed in succession, the assembly macro preprocessor (ap86) 
and the assembler (as86). Because of this, the implicit suffix rule .s.o: cannot 
be used; you should explicitly put a .s.o: rule in your makefile: 



A second difference involves the implicit rule .c: which tells make to build to 
an executable file from a C source file. Make expects that the executable file 
has no suffix, but the 8086/186 cross language tools expect a .x suffix (.X if -h 
option has been selected). The solution is to simply specify your own suffix 
rule (.c.x: or .c.X:) which performs the functionality of the .c: implicit rule: 



.s.o: 



$ (CC) 



$ (CFLAGS ) 



-c $* . s 



.c.X: 



$(CC) $ (CFLAGS) 



-o $*.X $*.c 
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Note The SunOS make command adds a "-target" option to the compiler command 

line. To remove this option, add the following statement to the beginning of 
the makefile: 

COMPILE. c= $ (CC) $(CFLAGS) $(CPPFLAGS) -c 



Make also has a mechanism for passing additional options to the compiler, 
assembler, and linker. The additional options are passed each time the 
program is invoked and are thus set only for "global" options. For example, to 
always have the compiler and assembler produce listings, one might use: 

CFLAGS = "-L" 
ASFLAGS = "-Lfnot" 

Some versions of make give default values for these options. 
Here is an example makefile: 

# These definitions are added to use the cc8086 cross tools. 
CC = cc8086 

# All object files (make knows how to generate them from 

# sources based on implicit rules). 

OBJECTS = main.o filel.o grammar. o 

# This dependency links the program together. 

program. x: $ (OBJECTS) 

$ (CC) $ (OBJECTS) -o program. x 

# This dependency causes make to recompile filel.c 

# whenever filel.h has been touched. 

filel.o: filel.h 

When run in a directory containing sources: 

main.c filel.c grammar. y filel.h 

The commands generated by HP-UX make will be: 

cc8086 -0 -c main.c 
cc8086 -0 -c filel.c 
yacc grammar. y 
cc8086 -0 -c y.tab.c 
rm y.tab.c 
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mv y.tab.o grammar. o 

cc8086 main.o filel.o grammar. o -o program. x 

This example assumes that /usr/hp64000/bin has been added to your PATH 
environment variable. 

You can see what commands will be generated by make by using the following 
command: 

make -n 
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To modify environment libraries 

To modify the environment-dependent library env.a, the startup routines 
crtO.o or crtl.o, or the monitor stub mon_stub.o: 

1 Set up directories for the different memory models. 

Select a directory from which you expect to run the compiler. The make utility 
will be used to create new environment-dependent libraries and object files 
which contain the changes made to the source files. As provided, Makefile 
assumes there are five directories named src, large, medium, compact and 
small in a parent directory. Makefile expects to be located in, and run from 
the src directory. The object and library-archive files will be built in the large, 
medium, compact, and small directories; the emulation monitor is built in the 
parent directory (the directory you are currently in). The following command 
sets up the needed directories. 

$ mkdir src large medium compact small 

2 Copy the source files. 

The following command copies the environment-dependent source files to the 
current directory. 

cp /usr/hp64000/env/hp<emuJ_env>/src/* src 



3 Edit the source files. 

The following command changes the permissions of the source files so that 
you will be able to save any changes you make while editing the files. 

cd src 
chmod 64 4 * 

Now you may edit the source files as needed. 

4 Run the "make" command. 
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The following command will create, for both large and small memory models, 
new environment-dependent library files, env.a, new startup and 
error-handling modules, crtO.o, crtl.o, init_stub.o, and div_by_0.o, and a new 
emulation monitor module, monitor.o, which is common to both memory 
models. 

make all 

In addition to the all target, other targets are available for the make command 
which will create only those files needed. A list of these available targets is 
displayed by the following command. 

make help 

The following command will remove unnecessary intermediate files left by the 
make all command. 

make clean 

Now return to the parent directory, 
cd . . 

5 Modify the default linker command file. 

The following commands copy the default I/O linker command file to the 
current directory so that you can edit it to load the environment file just 
created. (Copy linkcom.k if your programs do not use I/O .) 

cp /usr/hp64000/env/hp<emul_eiiv>/large/iolinkcom. k large 
chmod 644 large/iolinkcom. k 
vi large/iolinkcom. k 

Change all lines which read: 

LOAD /usr /hp 6 4 000 /env/hp<emul_erjT/>/large/env . a 

to 

LOAD large/env.a 

If small memory model is being used, do the same procedure as for the large 
memory except substitute small for large in all the commands. 

If the medium or compact memory model is used, follow the same procedure 
as for the large memory model, except substitute "medium" or "compact" for 
"large" in all the commands. 
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Similarly, if you have modified the startup module source file crtO.s or crtl.s, 
or the monitor stub mon_stub.s, you should also change the linker command 
file so that it loads the local version instead of the shipped version. 

If no emulation monitor is needed, the LOAD command for monitor .o maybe 
commented out or removed. The env.a library, which is loaded after monitor.o, 
will resolve the necessary external symbols. Note that monitor.o, when used, 
must be loaded before env.a. 



Note The environment for HP 64700 series emulators for the Intel family does not 

include a monitor.o file. These emulators use a background monitor which 
does not need to be linked to the user's code. 



Specifying the modified linker command file when compiling your program 
(with the -k option) will cause the linker to call in routines from the modified 
environment-dependent library. Remember to use -k < memory 
m odel> /iolinkcom.k to get the appropriate modified linker command file. 

About environment libraries 

Many files are linked into the C program from the environment libraries. 
These libraries reside in the subdirectories of /usr/hp64000/env and are 
designed to support the emulator (and simulator, if available). But these do 
more than just help you use the emulator. 

The 8086/186 C compiler has only limited information about the environment 
in which compiled programs will ultimately execute. All the high level 
functions depend on the environment libraries to provide the low level hooks 
into the execution environment (or target system). The supplied environment 
libraries provide the hooks necessary to operate in the emulator environment. 
They also serve as a pattern for you to create your own low level hooks to 
allow the 8086/186 C compiler to work in your own execution environment. 
You may either modify our environment files (the source code is provided) or 
use the files as a pattern to create your own equivalent files. HP has made 
every effort to narrow this "hook-up point" as much as possible, but you will 
need to make some modifications in order to run your programs in your own 
execution environment. 
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To view the on-line man pages 

• Use the host operating system's man command. 

You can display on-line "man pages" for any of the programs which make up 
the 8086/186 C Cross Compiler: 

• cc8086 

• cpp8086 

• clst8086 

Refer to the on-line man pages for detailed information about command-line 
options and compiler directives. 

Because the man pages contain important information which is not included 
in this manual, HP recommends that you print the cc8086 man page and keep 
it near your computer. 

The man pages are in the directory $HP64000/man. If the man command 
cannot find the man pages, check that you have added this directory to the 
MANPATH environment variable. 



Example To view the cc8086 on-line manual page, just type in the following command 

from the operating system prompt: 

man cc8086 

Information on the cc8086 compiler syntax and options will be scrolled onto 
your display. 
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C Compilation Overview 

An overview of the 8086/186 C Cross Compiler and a description of the ANSI 
C language. 
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Execution Environment Dependencies 

Providing the "standard I/O" and storage allocation C library functions creates 
dependencies on the environment in which programs execute. 

Since the 8086/186 C compiler is a tool to help you develop software for your 
own target system execution environments, HP has been careful about any 
execution environment dependencies associated with this compiler or its 
libraries. 

The compiler provides the "standard I/O" and storage allocation library 
functions; therefore, there are some environment dependencies to be aware of. 
The compiler isolates these environment dependencies to make it easier to 
tailor the compiler to your own target system execution environment. 

The execution environment-dependent routines provided with the 8086/186 C 
compiler are written to work in the HP development environments, but they 
need to be rewritten for target system execution environments. 
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C Compilation Overview 

An overview of the 8086/186 C compiler is shown in figure 2-1. The entire 
process is controlled by the command line fed to the compilation control 
routine. Rectangles in the diagram represent either data provided by the 
programmer (C source file, for example) or data produced by one of the 
circular processes (output listing, for example). Each process is described 
following the figure. 

In the following figure, the names of programs appear in parentheses. These 
names refer to the cross tools, and not to the native tools. For example, "cc" 
refers to cc8086 cross compiler and not to the native host cc compiler. 



41 



Chapter 2: C Compilation Overview 

C Compilation Overview 




Figure 2-1 . C Compilation Overview 
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Note When you use the cc8086 command, the 8086/186 C compiler generates 8086 

code. When you use the cc80186 command, the 8086/186 C compiler generates 
80186 instructions where it is optimal to do so. In cases where 80186-specific 
instructions have no advantage over 8086 instructions, 8086 instructions are 
generated. 

Except for the generation of 80186 instructions, the 8086 and 80186 compilers 
are identical. 

Throughout the remainder of the manual, this product is referred to as the 
8086/186 C compiler. You should take that to mean 8086/186 C Cross 
Compiler. 
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Compilation Control Routine 

The entire system is controlled by a compilation control routine, cc8086 (or 
cc80186 for the 80186). The compilation control routine calls in sequence: the 
C preprocessor (cpp8086), the C compiler (ccom8086S/C/M/L), optionally the 
peephole optimizer (opt8086), the assembly macro preprocessor (ap86), the 
assembler (as86), optionally the lister (clst8086), and the linker (ld86). Many 
of these programs maybe run individually using the cc8086 command's 
options. See the on-line man pages for the description of the command syntax 
and options. 

The librarian (ar86) is a separate tool for building archive files used by the 
linker. 

C Preprocessor 

The 8086/186 C preprocessor accepts C preprocessor directives which modify 
the source code that the compiler sees. This modification includes expansion 
of include files, expansion of macros, and management of conditional 
compilation. See the on-line man page for a description of the C preprocessor. 

C Compiler 

The 8086/186 C compiler accepts C language as defined by the ANSI C 
Standard. The compiler performs a translation with optional optimizations 
(see the "Optimizations" chapter) and emits an assembly language source file 
containing embedded directives which provide information to be used by the 
lister and later by the debugger and analyzer (see the "Compiler Generated 
Assembly Code" chapter). The compiler also emits error and warning 
messages to the standard error output. These messages include the original 
source line on which the error occurred with a pointer to the offending token. 

Peephole Optimizer 

The peephole optimizer is run when the "optimize" command line option is 
specified. It performs peephole optimization on the assembly output of the 
compiler. The optimizer makes allowances for volatile data types and 
embedded assembly code to avoid changing the functionality of the generated 
code. The optimizer works properly only on compiler-generated assembly 
code and is not a stand alone tool for use on hand-written assembly code. 
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Refer to the "Optimizations" chapter for more information on the peephole 
optimizer. 

Assembly Preprocessor 

The assembly preprocessor is the HP B1449 assembly preprocessor which 
accepts an assembly language source file (optionally containing symbolic 
debug information defined by special directives) and produces another 
assembly language file which has all assembly preprocessor macros, etc. 
expanded. The 8086/186 C compiler generates assembly preprocessor macros; 
therefore, assembly language code generated by the 8086/186 C compiler must 
pass through the assembly preprocessor before being assembled. 

Assembler 

The assembler is the HP B1449 assembler which accepts an assembly language 
source file (optionally containing symbolic debug information defined by 
special directives) and produces an object code file (optionally containing a 
representation of the symbolic debug information from the assembly source) 
and an optional listing for use by the lister in generating the final listing. The 
assembler also has a switch for generating HP 64000 format assembler symbol 
files. 

Source File Lister 

The source file lister is run when the "listing" command line option is 
specified. The lister uses the assembler source or listing, C source file, and 
include files to produce a listing. The listing includes embedded assembly 
language and, optionally, expanded include files and a cross reference table. 
The lister is controlled by "*LINE*" directives inserted by the compiler into 
the output assembly code. Because the lister is usually run by the compilation 
control routine, details of the lister directives are not described in this manual. 
See the on-line man page for the description of clst8086 command syntax and 
options. 

Librarian 

The librarian is the HP B1449 librarian which combines several object code 
files (generated by the assembler) into an archive file which the linker will 
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search when it tries to resolve external references. The libraries that are part 
of the compiler product are made with this librarian. 

Linker 

The linker is the HP B1449 linker which accepts several object code or archive 
files (generated by the assembler or librarian, respectively) and creates an 
absolute file containing all object code and symbols to be loaded. Optional 
load maps maybe generated as well as HP 64000 format linker symbol and 
absolute files. 



ANSI Extensions to C 

The B1493 8086/186 C Cross Compiler complies with ANSI/ISO standard 
9899-1990. In some cases, programs which compile with no errors on old C 
compilers will result in errors or warnings with this compiler. Although this 
may seem inconvenient, modifying the source will result in portability to other 
ANSI standard C compilers. 

Assignment Compatibility 

The ANSI standard has more carefully regulated assignment compatibility. In 
particular, pointers and integers are no longer considered to be assignment 
compatible without casts, and pointers to different typed objects are not 
assignment compatible without casts. 

Pointers and Integers 

Because assignments between pointers and integers occur often in many 
existing C programs, such assignments are warned rather than being flagged as 
errors by the 8086/1 86 C Cross Compiler. It is still recommended practice not 
to perform such assignments without casts. 

Pointers and Pointers 

The assignment of a "pointer to one type" to a "pointer to another type" only 
generates a warning message. However, the ANSI standard has provided a 
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new type (void) to which a pointer may point; the resulting "pointer to void" 
maybe assigned to any pointer. 

Function Prototypes 

Function prototypes allow you to specify the types of function parameters and 
whether a function accepts variable parameters. They allow the compiler to 
check the consistency of parameter types between declarations and calls of a 
function in a file. Because the linker does not check for incompatible calls 
across file boundaries, we recommend that you use an include file to declare 
the function at all reference and definition points. 

Function prototype information is used by the compiler to generate more 
efficient code by not widening passed parameters. That is, short and char 
passed parameters are not widened to int; and float parameters are not 
widened to double, as is the case in the absence of function prototypes. 

Old style function declarations (those without any parameter information) 
continue to have the same meaning as before. All short and char parameters 
are widened to int, and all float parameters are widened to double at the 
function call. The appropriate inverse conversions are performed at function 
entry. Old style and prototype declarations for the same symbol can coexist as 
long as all of the parameter types specified in the prototype are the widened 
types and as long as the ellipsis is not used. It is good practice to convert all 
declarations to prototype syntax if prototypes are going to be used. 

The consistency checking between the type of expression passed as a 
parameter to a prototyped function and the declared type of the corresponding 
parameter requires that the two types be assignment compatible. The 
parameter expression will be converted to the formal parameter type prior to 
its value being passed. 

The following is an example of function prototype usage: 

extern int printf (const char ^format, ...); 

/* Note the optional use of identifier "format" to document the parameter's 
meaning. The ellipsis indicates zero or more additional parameters. */ 

extern float float_operat ion ( float , float ) ; 

/* In this case, only type names are given for the parameters. */ 

/* The following is the prototype syntax for a function definition. */ 

void func(int i) 
{ 

float f; 
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f = f loat_operation (i, 2.0). 



The int "i" and the double "2.0" will be converted to float 
before being passed (the "2.0" is converted at compile time) . 
Both parameters are passed as floats without the expensive 
run time conversion to double which old style functions cause. */ 



Pragmas 

Pragmas are special preprocessor directives which allow compilers to 
implement special features. By definition, any pragma that a compiler does 
not understand will be ignored. However, because pragmas allow compilers to 
deviate from the standard, their number has been kept to a minimum. 

The pragmas which the 8086/186 C compiler understands are listed below. 
Pragmas which are not recognized cause a warning message to be written to 
the standard error output. 

# pragma SEGMENT 

Provides for renaming the default program segment names. (Refer to the 
"Segment Names" section of the "Embedded Systems Considerations" chapter 
for more information.) 

# pragma DS 

Provides for re-specifying which segment will be accessed DS-relative. (Refer 
to the "Segment Names" section of the 'Embedded Systems Considerations" 
chapter for more information.) 

# pragma ASM/END ASM 

Provides for including assembly language in the C source file. (Refer to the 
"Using Assembly Language in the C Source File" section of the "Compiler 
Generated Assembly Code" chapter for more information.) 

# pragma FUNCTION ENTRY/EXIT/RETURN 'C_string" 

Provides for including assembly language instructions in the function entry 
and exit code of the compiler-generated assembly code. (Refer to the "Using 
Assembly Language in the C Source File" section of the "Compiler Generated 
Assembly Code" chapter for more information.) 
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# pragma INTERRUPT 

Provides for implementing functions as interrupt routines. (Refer to the 
"Implementing Functions as Interrupt Routines" section of the "Embedded 
Systems Considerations" chapter for more information.) 

# pragma ALIAS 

Provides for the naming of an assembly language symbol associated with a C 
source file symbol. (Refer to the "Assembly Language Symbol Names" section 
of the "Compiler Generated Assembly Code" chapter for more information.) 

The void Type 

A new type, void, has been added by ANSI. It has two fundamental purposes. 
The first is to allow a function to be defined to have no return value (i.e., a 
procedure). Since void typed objects cannot be assigned to other objects, such 
procedures cannot be used in a context where a return value is required. (Of 
course, the protection afforded by this mechanism is limited to programs 
where functions are declared with a void return type using old style 
declarations or function prototypes.) 

The second use of type void is to declare generic pointers. By definition, 
pointers to void, e.g., "void *genericPtr;", are assignment compatible with 
pointers to any other type. This can also be a convenient type for the return 
type of a function such as malloc whose result is then assignment compatible 
with any pointer. 

The volatile Type Modifier 

The type modifier volatile specifies that a particular variable's value may 
change from one read to another or following a write. An obvious example of 
such a "variable" is an I/O port in an embedded system. The volatile type 
modifier informs the compiler of this behavior so that the compiler can avoid 
performing optimizations which assume that variables' contents are not 
changed unexpectedly. (Refer to the "Effect of volatile Data on Peephole 
Optimizations" section in the "Optimizations" chapter; also, refer to "The 
volatile Type Modifier" section in the "Embedded Systems Considerations" 
chapter for examples of its use.) 
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The const Type Modifier 

An object declared with the const type modifier tells the compiler that the 
object cannot be assigned to, incremented, or decremented; statements which 
attempt to do so will cause errors. Pointers to const storage cannot be 
assigned to pointers to non-const storage. Objects declared with the const 
type modifier can be accessed, but they cannot be written to. An object 
declared with the const type modifier, which has static storage class, is placed 
in the CONST segment (see the "# pragma SEGMENT" section in the 
"Embedded Systems Considerations" chapter). Some examples of how the 
const type modifier is used follow. 

static const char message!] [7] = { 

"First ", 
"Second", 
"Third " 

}; 

const char *cnst_chr_ptr; /* The pointer may be modified, */ 

/* but that which it points to */ 
/* may not. */ 

char *const ptr; /* The pointer may not be modified,*/ 

/* but that which it points to may.*/ 

const char *const ptr; /* Neither the pointer nor that */ 

/* which it points to may be */ 
/* modified. */ 
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Translation Limits 

The ANSI C Standard has set standard translation limits which must be met or 
exceeded by conforming implementations. The following list meets or exceeds 
all such limits put forth by the standard. 

• Approximately 50 nesting levels in compound statements, iteration 
control structures, and selection control structures. 

• Unlimited levels of nesting in preprocessor conditional compilation 
blocks. 

• Approximately 100 pointer, array, and function declarators modifying a 
basic type in a declaration. 

• Limited to 128 levels of expression nesting. 

• There are 255 significant case- sensitive characters in an internal identifier. 

• There are 255 significant case-sensitive characters in a macro name. 

• There are 30 significant case-sensitive characters in an external identifier. 

• Limited to 2 16 -2 bytes of local variables in one function block. 

• Unlimited simultaneous macro definitions. 

• Limited to 2 16 -2 bytes of parameters in function definition and call. 

• Limited to 127 parameters in preprocessor macro. 

• Limited to 1024 characters in a logical source line. 

• 1023 characters in a single string literal (1024 including a trailing null 
character). There is no limit on the size of string made from adjacent 
string literals. 

• A single object maybe as large as 2 16 -2 bytes in size. 

• Unlimited nesting levels of include files. 

• Unlimited number of cases in a switch statement. 

• Size of a switch statement body is limited to 2 16 -1 bytes of generated code. 



51 



Chapter 2: C Compilation Overview 

ANSI Extensions to C 




52 



Chapter 3: Internal Data Representation 



3 



Internal Data Representation 

How arithmetic and derived data types (arrays, pointers, structures, etc.) are 
represented in memory. 
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This chapter does not describe how to use data types in your programs. Refer 
to The C Programming Language for information such as escape sequences, 
printf conversions, and declaration syntax. 



Arithmetic Data Types 

The arithmetic data types are listed in the following table: 
Table 3-1 . Arithmetic Data Types 



Type 


# of Bits 


Range of Values (Signed) 


(Unsigned) 


char 


8 


-128 to 127 


0 to 255 


short 


16 


-32768 to 32767 


0 to 65535 


int 


16 


-32768 to 32767 


0 to 65535 


long 


32 


-2147483648 to 2147483647 


0 to 4294967295 


float 


32 


+ /- 1.18 x 10~ 38 to + /- 3.4 x 10 38 




double 


64 


+ /- 2.23 x 10" 308 to + /- 1.8 x 10 308 





The integral data types (char, short, int, and long) are signed by default; 
however, they maybe used in combination with the unsigned keyword to yield 
unsigned data types (unsigned by itself means unsigned int). All integral data 
types use two's complement representation. 

Floating-Point Data Types 



Floating-point data types are stored in the IEEE single and double precision 
formats. Both formats have a sign bit field, an exponent field, and a fraction 
field. The fields represent floating-point numbers in the following manner: 

Floating-Point Number = <sign> l.<fraction field> x 2(<exponent field> - bias) . 

Sign Bit Field. The sign bit field is the most significant bit of the 
floating-point number. The sign bit is 0 for positive numbers and 1 for 
negative numbers. 
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Fraction Field. The fraction field contains the fractional part of a 
"normalized" number. "Normalized" numbers are greater than or equal to 1 
and less than 2. Since all normalized numbers are of the form 
"1 .XXXXXXXX", the "1" becomes implicit and is not stored in memory. The 
bits in the fraction field are the bits to the right of the binary point, and they 
represent negative powers of 2. For example: 

0.011 (binary) = 2~ 2 + 2~ 3 = 0.25 + 0.125 = 0.375. 

Exponent Field. The exponent field contains a biased exponent; that is, a 
constant bias is subtracted from the number in the exponent field to yield the 
actual exponent. (The bias makes negative exponents possible.) 

If both the exponent field and the fraction field are zero, the floating-point 
number is zero. 



NaN. A NaN (Not a Number) is a special value which is used when the result 
of an operation is undefined. For example, adding positive infinity to negative 
infinity results in a NaN. 



Float 



The float data type is stored in the IEEE single precision format which is 32 
bits long. The most significant bit is the sign bit, the next 8 most significant 
bits are the exponent field, and the remaining 23 bits are the fraction field. The 

bias of the exponent is 127. The range of single precision format values is from 

38 38 

1.18x10" to 3.4x10 . The floating-point number is precise to 6 decimal 
digits. 



31 30 23 22 

S Exp. + Bias Fraction 



0 


000 


0000 


0 


000 


0000 


0000 


0000 


0000 


0000 = 


0.0 


0 


011 


1111 


1 


000 


0000 


0000 


0000 


0000 


0000 = 


1.0 


1 


011 


1111 


1 


011 


0000 


0000 


0000 


0000 


0000 = 


-1 . 375 


1 


111 


1111 


1 


111 


1111 


1111 


1111 


1111 


1111 = 


NaN (Not a 
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Double 

The double data type is stored in the IEEE double precision format which is 
64 bits long. The most significant bit is the sign bit, the next 1 1 most significant 
bits are the exponent field, and the remaining 52 bits are the fraction field. The 
bias of the exponent is 1023. The range of double precision format values is 

308 308 

from 2.23 x 10" to 1.8 x 10 . The floating-point number is precise to 15 
decimal digits. 



63 


62 


52 


51 










0 




S 


Exp. + Bias 


Fraction 




0 


000 0000 


0000 0000 0000 


0000 . 


. 0000 


0000 


0000 


0000 


= 0.0 


0 


011 1111 


1111 0000 0000 


0000 


0000 


0000 


0000 


0000 


= 1.0 


l 


011 1111 


1110 0110 0000 


0000 . 


. 0000 


0000 


0000 


0000 


= -0 . 6875 


l 


111 1111 


1111 1111 1111 


1111 


1111 


1111 


1111 


1111 


= NaN 



Precision of Real Number Operations 

In the absence of the "generate code for the 8087" command line option, all 
real number operations are accomplished by calls to the real number routines 
(described in the "Conversion" and "Floating-Point Routines" sections of the 
"Small Memory Model Run-Time Routines" and "Large Memory Model 
Run-Time Routines" chapters) or to math library routines which eventually 
call run-time library routines. With the "generate code for the 8087" command 
line option, most real number operations are performed in-line with 8087 
instructions. 

All of this has a subtle effect on the precision of floating-point results. 

Without the 8087. When routines are used to perform floating-point 
operations, all intermediate results are truncated to 64-bit precision 
immediately, and no 80-bit intermediate results are carried on into subsequent 
calculations. The precision of the results reflects this implementation. 

With the 8087. When the "generate code for the 8087" (-f) command line 
option is used, many intermediate results are kept with 80 bits of precision and 
are passed on into subsequent operations without truncation. 

The 8087 allows you to control its precision, rounding, trapping, and infinity 
behaviors. You may change the behavior of the 8087 by using the 
_set_fp_control() function, which is described under _fp_error in the 
"Libraries" chapter. 
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Characters 

In addition to the char type, the 8086/186 C compiler supports wide 
(extended) characters with the wchar_t type. The wchar_t type is 
implemented as unsigned long. Constants in the extended character set are 
written with a preceeding L modifier. Library routines which support wide 
characters are described under mblen in the "Libraries" chapter. 

Multi-byte characters are not supported. 

If a multi-character constant (for example, 'abc') is encountered, the compiler 
multiplies the value of the first character by 256 and adds the value of the 
second character. If there are remaining characters, the new value is 
multiplied by 256 and the next character is added until no more characters are 
left. (Some previous versions of the compiler technology simply accepted the 
first character and discarded the others.) 
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Derived Data Types 

The following objects are derived data types. The sizes of each data type (or 
the calculation used to determine the size) are listed. 



Pointers 



16-bits (Small memory model); 32-bits (Large memory 
model). 



Arrays 
Structures 



(Number of elements)*(Size of one element). 

Sum of the sizes of each member. (Members, as well as 
the structure itself, maybe padded for alignment.) 



Unions 



Size of the largest member. (This member, as well as 
the union itself, maybe padded for alignment.) 



Enum types 



1 or 2 bytes depending on the constant values of the 
elements. 
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Pointers 

Pointers are addresses which point to stored values. Pointers occupy four bytes 
(two bytes for the small memory model) and are aligned on two byte 
boundaries. The following program is a simple example of how pointers are 
used. 



main ( ) 
{ 



int value; 

int *ptr /* "ptr" is of type pointer to "int". */ 

value = 256; 

ptr = Svalue; /* "ptr" = the address of the location */ 
/* at which "value" is stored. */ 



Arrays 

Arrays are made up of a fixed number of elements of the same type. 
Multi-dimensional arrays can be thought of as arrays of arrays (of arrays, etc.) 
where each array represents a single dimension. Index values for each 
dimension are used to access the elements of a multi-dimensional array. 

The amount of storage allocated for an array is the sum of the space used by 
all its elements. An array is aligned on the alignment boundary of its elements. 
For example, a short array with 10 elements would use 20 bytes and be aligned 
on a two byte boundary. 

The first element of a one-dimensional array (index equals zero) is located at 
the lowest address of the storage allocated for the array. Elements of 
multi-dimensional arrays are stored in row-major order (in other words, the 
rightmost index changes more rapidly with successive memory locations). 

The following program shows some simple arrays. 



float fpns[10]; /* 10*4 = 40 Bytes of storage allocated */ 

/* at 2-byte aligned address. */ 

main ( ) 
{ 

int array [4] [7]; /* 4*7*2 = 56 Bytes allocated */ 

int i, j; /* on the stack. */ 

fpns[l] = 1.0; 

for (i = 0; i < 4; i++) 

for (j = 0; j < 7; j++) 
array [ i ] [ j ] = 0 ; 
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Strings 

Strings are a sequence of characters or escape sequences enclosed in double 
quotes ("). Strings maybe used in two distinct contexts. The first is in C 
program statements or as intitializers of type char * where they are treated as 
if they are of type "const char *". For example: 

char *p, *q = "abc"; 
p = "xyz"; 

When used in such a context, the compiler places the string, together with an 
additional NULL (0) termination character, in the named CONST linker 
segment (named "const" by default). 

The second context in which strings maybe used is as initializers of arrays of 
char. If the initialized array is an automatic, the initialization occurs at 
run-time, and the compiler places the string and NULL terminator in the 
named CONST linker segment just as above. If, however, the array being 
initialized is a static, the initialization occurs at load-time (or is in ROM). For 
example: 

const char string [] = "abcdefghi"; 

When a string is used to initialize an array, the compiler places the initialized 
array in either the named DATA linker segment (if the array's type is not 
"const") or in the named CONST linker segment (if the array's type is "const"). 
A terminating NULL (0) character is appended to the string only if there is 
room in the declared array (or if it is "open" as above). 



Note Trying to change the value of a string constant may cause unwanted side 

effects. The reason for this is explained in the "Optimizations" chapter. 



The compiler accepts hexadecimal escape sequences of unlimited length. The 
example below is interpreted as a single hex value: 

*str = "\x064f"; 

In order to produce the string "df ', you could modify the string in the following 
way: 

*str = "\x064" "f"; 
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Structures 

Structures are named collections of members. Structure members maybe of 
different types, they maybe specified as bit fields, or they may even be pointers 
to the structure in which they are defined (self -referential structures). 

Structures maybe passed as parameters to and returned from functions. (See 
the "Stack Frame Management" section of the "Compiler Generated Assembly 
Code" chapter for more information on how structures are passed to and 
returned from functions.) 

The amount of storage allocated for a structure is the sum of the space 
required by all its members, the alignment padding between members, and 
padding at the end of the structure to make its size a multiple of two bytes. For 
example, a structure whose members are a char, an int, and a double would be 
allocated 12 bytes (one byte following the char is "wasted" to align the int). 
Members are located in the allocated space in the order that they are declared. 

An example of a simple structure follows. 



struct example { /* 12 bytes of storage allocated at 2-byte boundary, 

char c; /* First byte of structure. */ 

int i; /* Begins at 3rd byte of structure. */ 

double d; /* Begins at 5th byte of structure. */ 

} var; 



main ( ) 
{ 



var . c = a ; 
var . i = -1; 
var.d = 1.0; 



When the 'byte align data" option is used, there will be no alignment padding 
between members or at the end of a structure. The structure size maybe other 
than a multiple of two bytes. 
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struct { 



Bit Fields 

Bit fields are structure or union members which are defined as a number of 
bits. A colon separates the length of a bit field from the declarator. Bit fields 
can be signed (declared as plain integral types) or unsigned (declared as 
unsigned integral types). All integral types are allowed in bit field 
declarations, but are converted to int or unsigned int. The high order bit of a 
signed bit field is the sign bit. 

Bit fields are packed from the high-order bits to the low-order bits in the 
words of memory they occupy. Bit padding can be generated by omitting the 
name from the bit field declaration. Consecutive bit fields are packed 
adjacently regardless of integer boundaries. However, a bit field with a 
specified width of zero will cause the following bit field to start on the next int 
(word) boundary. 

Examples of bit field declarations follow. 



int fl:4; /* fl is a signed bit field, */ 

/* occupying bits 0-3 of the */ 

/* first word. */ 

/* */ 

unsigned :8; /* 8 bits of padding occupy */ 

/* bits 4-11 of the first */ 

/* word. */ 

/* */ 

unsigned f2:8; /* f2 occupies bits 12-15 of the */ 

/* first word and bits */ 

/* 0-3 of the second word. */ 

/* */ 

int :0,f3:7; /* f3 occupies bits 0-6 of */ 

/* the third word. */ 
a; /* The size of the structure is */ 

/* 6 bytes. */ 
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Unions 

Unions are like structures except that each member has a zero offset from the 
beginning of the union. Unions provide a way to access the same memory 
locations in more than one format. A simple example of a union is shown 
below. 



union { 

float fp_rep; 
struct { 

unsigned int lowbits; 
unsigned int :15; 
unsigned int sign : 1; 

} parts 
} fp_num; 

main ( ) 
{ 

f p_num . f p_rep = 1.0; 

if ( fp_num . part s . sign == 0) 

fp_num . part s . sign = 1; 



Enumeration Types 

Enumeration type declarations define elements of a finite set. Each element 
of the enumerated type becomes a constant. The first element is equal to a 
constant value of 0, the second is equal to 1, and so on. You can assign a 
particular constant value to an element, and the values of the elements which 
follow will increment from that value. 

An enumeration type is considered to be the smallest integral type which can 
represent all the values of the enumeration. 

• If the constant values for all elements are between -128 and + 127, the 
enumeration type is allocated the same space as char types. 

• If the condition above is not true, but the constant values for all elements 
are between -32768 and + 32767, the enumeration type is allocated the 
same space as short int types. 

• If the constant value of any element is outside the range 
-32768 to + 32767, it is an error. 
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An enum typed variable can be used in expressions wherever integral typed 
variables are allowed. An enumerated constant is always of type integer. The 
following program shows a simple enumerated type. 

enum color {yellow, red, green, blue=8, violet} paint; 

/* The elements of the enumeration type "color" equal the */ 
/* following constants: yellow = 0, red = 1, green = 2, */ 
/* blue = 8, and violet = 9. */ 



main ( ) 
{ 



enum color marker; 

if (marker == green) 
{ 

paint = marker; 

marker++; /* This statement is allowed, but */ 

/* marker = 3 instead of "blue" */ 
/* which is 8. */ 



The values of an enumerated type are considered to be declared the moment 
they are encountered in the source file. Thus it is possible to have a 
declaration like the following: 

enum {apple, orange = apple} e; 



Alignment Considerations 

Variable and constant data, as opposed to executable instructions, maybe 
aligned or padded by the compiler. In this context, aligned is defined to mean 
that the memory allocated to the variable begins at a particular byte boundary 
(e.g., an alignment of two bytes means that a variable's absolute address is a 
multiple of two); padded is defined to mean that the size of a type was rounded 
up to guarantee that the number of bytes in that type is a multiple of two. 

Arrays are aligned according to their element type's alignment and are not 
padded. Note, however, that an array's elements may be padded (if it is an 
array of structures or unions). 

Structure members are aligned relative to the start of the structure (and 
padded if they are structures or unions) in accordance with their type. 
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Unless function prototypes are used (see the "ANSI Extensions" section in the 
"C Compiler Overview" chapter), all char and short parameters are widened to 
ints when they are passed and, thus, follow int alignment rules when they are 
passed. Note that inside a called function, char or short parameters are 
reduced to their normal char and short size. 

Alignment can be changed by using the compiler's 'byte align data" (-Q) 
option. In the presence of this option, data is aligned at byte boundaries. 

The following table summarizes the default alignment and padding of the 
various data types when the 'byte align data" option is not used. 



Note If the 'byte align data" option is used, alignment is always 1 and there is no 

padding. 



Table 3-2. Arithmetic Data Type Alignment 



Data Type 


Alignment 


Padded? 


char 


1 


N 


short 


2 


N 


int 


2 


N 


long 


2 


N 


pointer 


2 


N 


float 


2 


N 


double 


2 


N 


struct 


2 


Y 


union 


2 


Y 
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Alignment Examples 

These examples assume that the "byte, align data" option is not used. 

Default alignment dictates that a char variable followed by an int variable 
"wastes" one byte of memory between the two objects. Note that there are no 
"wasted" bytes when a char variable is followed by an array of char, but one 
byte is "wasted" when a char variable is followed by a structure. 

The sizeof bytestruct declared with: 

struct {char element;} bytestruct; 

is two (the minimum sizeof any struct type) and the sizeof biggerstruct 
declared with: 

struct {char element 1; 

int element2;} biggerstruct; 

is four (one for element 1, one "wasted" for alignment, two for element2, and 
none for padding as the size is a multiple of two). 
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Compiler Generated Assembly Code 

Description of the assembly code generated by the compiler. 
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The compiler generates assembly code for the HP B1449 assembly macro 
preprocessor (ap86) and assembler (as86). Knowing how the compiler 
generates this code will help you to write assembly language routines that 
interface with C functions. 

In this chapter you will find information about the following subjects: 

• Assembly language symbol names 

• Debug directives 

• Stack frames (how parameters are passed to and from C functions) 

• Register usage 

• Run-time error checking 

• Memory model mismatch checking 

• Ways to include assembly language in a C source file 
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Assembly Language Symbol Names 

The compiler prefixes characters to the names given in the C source (to 
prevent potential conflicts with assembler reserved words) when generating 
assembly language symbols to represent addresses and stack offsets of C 
variables. 

Symbol Prefixes 
The _ Prefix 

Externs, globals, statics, and functions have an underscore (_) prefix. You can 
change the prefix for external variables (externs, globals, and functions) to a 
different string by using a cc8086 option (-Wc,-1). Refer to the on-line man 
page for more information on changing this prefix character. 

The S_ Prefix 

Parameters and automatics have "S_" prefixed. The "S" indicates symbols that 
are SET equal to stack offsets. 

The L_ Prefix 

The only other symbol names from the C source which are passed on to the 
assembly code are C label names. These labels have "L_" and a unique ASCII 
number prefixed to them in the generated assembly code. 

See figure 4-1 for an example of how the compiler creates symbol names. 

These symbol names are no? used by debuggers and emulators unless the 
debuggers and emulators consume HP format absolute files. The C source 
symbol names are defined using debug directives (see the following "Debug 
Directives" section). 
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/* Assembly Symbol Name: */ 

/* */ 

float ext_var; /* _ext_var */ 

/* */ 

main() / * _main * / 

{ /* */ 

char auto_var; /* S_auto_var */ 

static int number; /* _l_number */ 

/* */ 

auto_var = 'a'; /* */ 

goto label; /* */ 

label: /* L_2_label */ 

function (number) ; /* */ 

} /* */ 

/* */ 

int number; /* _number */ 

/* */ 

function (i) /* _function */ 

int i; /* S_i */ 

{ /* */ 

i = 1; /* */ 

} /* */ 



Figure 4-1 . Examples of Generated Symbol Names 



Situations Where C Symbols are Modified 

There are four cases where the compiler modifies the names of C variables to 
guarantee that they are unique in the assembly code: 

1 If a parameter or automatic name exceeds 29 characters in length, then it 
must be made unique since the assembler only recognizes 31 (29 + 2 for 
"S_") significant characters in a symbol. 

2 If there is a variable with the same name in a containing scope in the C 
source, then a parameter or automatic name must be made unique since 
both symbols must exist at the same time in the assembler (which doesn't 
understand scoping). 

3 All local statics (those declared inside a function) are made unique, since 
a global static of the same name maybe declared later. 

4 External statics (those declared outside a function) are made unique if 
their name exceeds 30 characters in length since the assembler only 
recognizes 31 (30 + 1 for "_") significant characters in a symbol. 
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In all four cases, symbol names are made unique by inserting a unique ASCII 
number and an underscore between the initial underscore (or "S_") and the C 
name. For example: 

_12 3_name 
S_12 3_name 

# pragma ALIAS 

Syntax: 

# pragma ALIAS Csymbolname Assemsymbolname 

# pragma ALIAS Csymbolname "Assemsymbolname" 

This pragma allows overriding of the C compiler algorithm for converting C 
source file symbol names into unique assembler symbol names (the algorithm 
generally prefixes an "_" or "S_"). This pragma should be used with great care 
as it may generate assembly-time errors due to conflicts between 
Assemsymbolname and other assembly language symbols. Use the quotation 
marks if the Assemsymbolname would not be a valid C identifier. This pragma 
should be placed before any references to the symbol. 

Compiler Generated Symbols 

The compiler generates assembly language labels for C loops, switch 
statements, and other constructs which require labels. The name of the label 
is related to the use of the label; for example, the label "forLoop3" might be 
used to implement a for loop. 
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Debug Directives 

If the "strip symbol table information" compiler command line option is not 
used, the compiler generates all the HP B1449 debug directives necessary to 
use debugger, emulation, and analysis tools. This debug information consists 
of source file and line references, type names and structure, symbol type and 
access information, and function call information. One LINE directive is 
output for each C source statement to associate the generated assembly code 
with the C source file line number. 



Stack Frame Management 

In block-structured languages (C, Pascal, etc.), the stack is used to pass 
parameters into and receive results from each of the blocks which make up the 
program. In C, these blocks are called functions. In addition to passing values 
and returning results, the stack is used for a function's local variables and to 
buffer register variables. The area of the stack used by a function is called a 
"stack frame". To illustrate what makes up stack frames and how they are 
managed, one must observe what happens to the stack when a function is 
called; these events are listed below and described in this section. 



Note This section applies only to C function calls. Run-time libraries invoked in 

compiler-generated code may use different (and more efficient) stack frame 
management because these calls are not constrained by C language calling 
conventions. 



• Space is reserved for a structure result (if the size returned is greater than 
4 bytes). 

• Parameters are pushed (last is pushed first). 

• A pointer to the result address is pushed (if size returned is greater than 4 
bytes). 

• The subroutine call is made and the return address is pushed. 

• The old frame pointer is pushed. 
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• Space for automatics (locals) is allocated. 

• The old Data Segment (register DS) is pushed and DS is loaded with the 
new data segment paragraph number. (Large memory model only.) 

• The old register variable (register SI) is pushed to buffer its value. 

• The complete internal state of the 8087 is pushed if the "generate code for 
the 8087" command line option was used and one or more floating-point 
register variables are used in the function. 

• During function execution, intermediate values may be stored on the stack 
temporarily. 

• Function return values are stored in working registers or returned 
indirectly through a pointer on the stack (possibly into space reserved on 
the stack). 

• At function exit, the 8087 state, if it was saved, is restored; any 8087 
registers which were saved are restored; register variables are restored and 
locals are deallocated; and the calling routine deallocates parameters and 
uses the structure result. 

The general format of a stack frame is shown in figure 4-2. An example of the 
code generated for stack frame management is shown in figure 4-3. 
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High Address 



Frame pointer (BP) 



Stack pointer (SP) 
Low Address 



Used stack space 

Reserved space for 
structure result 

Last parameter 

First parameter 

[segment] Result 
[offset] address 

[segment] Return 
[offset] address 



Old frame pointer 
(BP) 



Last local 
First local 



Buffered data 
segment (DS) 



Buffered register 
variable (SI) 



8087 register 
variables 

Temporaries 
Top of stack 



Absent if result is < = 4 bytes or if 
result is returned through a variable. 

Absent if no parameters are passed. 
(Last passed parameter is pushed 
first.) 

Absent if size returned is < = 4 bytes. 
(Address size is 2 words.) 

(Address size is 2 words.) 



Absent if there are no parameters or 
locals. (Size is 1 word.) 

Absent if function does not declare 
any local (automatic) variables. (Last 
declared local is first on stack.) 

Absent if function does not access 
DS-relative static data. 

Absent if function does not use 
register variables. 

Present when "-f option is used and 
8087 register variables are used 

Stack changes as temporaries are 
saved and used in expressions. 



Figure 4-2. Stack Frame Format 
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HPB1493-19303 8086 C Cross Compiler A. 04. 01 esfm.c 



;MKT:@(#) B1493-19303 A. 04. 01 8086 C CROSS COMPILER 



03May95 



Memory Model : large 



5PAGEWIDTH (230) 
$NOPAGING 

NAME "esfm" 
%DEFINE (MM_CHECK_) (MM_CHECK_L) 
%DEFINE (lib) (lib) 
%DEFINE (SS) (SS) 
%DEFINE (DS) (DS) 
%DEFINE (ALIGN) (WORD) 
%DEFINE (DALIGN) (WORD) 

prog_esfm SEGMENT %ALIGN PUBLIC ' 

%DEFINE (CodeSegment ) (prog_esfm) 
1 typedef struct { 

int month, day , year ; 

} date; 



CODE' 



_mam 



int year 

main ( ) 
{ 

PUBLIC 
ASSUME 
PROC 



_main 

CS : % Code Segment , DS : data 
FAR 



%SET (SAVE_ALL_NPX, 2) 



PUSH 

MOV 

SUB 

PUSH 

MOV 

MOV 

%SET (S_d, -6) 

9 
10 
11 

SUB 
PUSH 
MOV 
PUSH 
MOV 
PUSH 
PUSH 
PUSH 
PUSH 
MOV 
ADD 
PUSH 
PUSH 
CALL 
ADD 
12 } 
functionExitl : 



BP 

BP, SP 
SP, 6 
DS 

AX, data 
DS, AX 

date 



d, set_date ( ) 



Space reserved for 
structure result. 




set_date (d, 5 , 1 
SP, 6 

%DS:WORD PTR _year[0] 
AX, 18 
AX 
AX, 
AX 



Parameters 
pushed. 



SS:WORD PTR [BP+%S_d+0+4 ] 
SS:WORD PTR [BP+%S_d+0+2 ] 
SS:WORD PTR [BP+%S_d+0] 
AX, SP 
AX, 12 
SS 
AX 

FAR PTR _set_date 
SP, 6+0+12+4 



Structure 
result address 
pushed. 



Function 
call. 



Stack pointer incremented 
(parameters popped). 



Figure 4-3. Example Stack Frame Management Code 
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POP 
MOV 
POP 

returnLabell : 
RET 
ENDP 



DS 

SP, BP 
BP 



_main 
13 
14 
15 
16 
17 



date set_date (x,mo, da, yr) 
date x; 

mo, da, yr; 



int 
{ 

PUBLIC 
ASSUME 
date 



_set_date 

CS : % Code Segment , DS : NOTHING 



PROC 



_set_ 

%SET (SAVE_ALL_NPX, 2) 



FAR 



%SET ( 
%SET ( 
%SET ( 
%SET ( 
%SET ( 
%SET ( 
; S_i3 
18 
19 
20 
21 



PUSH BP 
MOV BP,SP 
SUB SP,16 
PUSH SI 

S_x, 10) 

S_mo ,16) 

S_da, 18) 

S_yr, 20) 

S_il, -16) 

S_i2, -8) 
is in register SI. 

double 



Old frame pointer 
pushed and 
space for locals 
allocated. 



register int 



il, i2; 
i3; 



22 
23 
24 



25 
f unct 



retur 
_set 



MOV 
MOV 

MOV 
MOV 

MOV 
MOV 

PUSH 
PUSH 
PUSH 
LES 
CLD 
POP 
STOSW 
POP 
STOSW 
POP 
STOSW 
} 

ionExit2 : 

POP 

MOV 

POP 
nLabel2 : 

RET 
date 



x. month = mo; 

AX, SS: WORD PTR [BP+%S_mo+0] 
SS:WORD PTR [BP + %S_x+0 ] , AX 
x.day = da; 

AX, SS: WORD PTR [BP+%S_da+0] 
SS:WORD PTR [BP+%S_x+2 ] , AX 
x.year = yr; 

AX, SS: WORD PTR [BP+%S_yr+0] 
SS:WORD PTR [BP+%S_x+4 ] , AX 
return (x) ; 
SS:WORD PTR 
SS:WORD PTR 
SS:WORD PTR 



[BP+%S_x+0+4 ] 
[BP+%S_x+0+2] 
[BP+%S_x+0] 



DI,SS:DWORD PTR [BP+6] 

AX 

AX 

AX 



Structure 

result 

returned. 



si 

SP, BP 

BP 



Function exit. 



Figure 4-3. Example Stack Frame Mgmt. Code (Cont'd) 
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prog_ 


esfm 


ENDS 


data 


SEGMENT 


%DALIGN PUBLIC 




PUBLIC 


_year 




EVEN 




_year 


LABEL 


BYTE 




DW 


87 


data 


ENDS 






EXTRN 


%MM_CHECK_: BYTE 


mm_check 


SEGMENT BYTE COMMON 




DW 


OFFSET %MM_CHECK_ 


mm_check 


ENDS 




END 





Figure 4-3. Example Stack Frame Mgmt. Code (Cont'd) 
Structure Results 

C allows functions to return results of type struct. Although most function 
results are returned in a working register (AL, AX, DL-AX, or DX-AX), 
structures greater in size than 4 bytes are returned to a location specified by 
the result location pointer. The result location pointer is pushed onto the 
stack after the parameters and before the return address. 

In a C statement such as "structure = f(x)", the address of the variable 
"structure" maybe pushed as the result location pointer, and the called 
function will return its resultant structure directly into memory reserved for 
the "structure" variable. 

In other statements, such as "i = f(x).field", space must be reserved on the 
stack (prior to pushing parameters) to hold the function structure result. The 
address of this reserved stack space will be pushed as the result location 
pointer (after the parameters and before the return address), and the function 
will return its resultant structure into the reserved stack space. This approach 
maintains reentrancy for functions returning structures. 

Parameter Passing 

Parameters are pushed on the stack in right to left order as they appear in the 
function call (in other words, the last passed parameter is pushed first). 
Unless function prototypes are used (see the "ANSI Extensions" section in the 
"C Compiler Overview" chapter), parameters of type char are rounded up to 
int when passed, and parameters of type float are rounded up to double when 
passed. 
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After the parameters (and, possibly, a result address) are pushed, the function 
is called. The subroutine call pushes the return address on the stack following 
the parameters. 

Pushing the Old Frame Pointer 

Within a called function's prolog, a PUSH BP instruction followed by a MOV 
BP,SP instruction (or just a ENTER instruction) is used to save the old frame 
pointer (BP) and set up the new stack frame. This occurs only if one or more 
of the following conditions is true: 

• The "optimize" option is off. 

• The "run-time error checking" option is on. 

• Automatic variables exist for the current function. 

• Parameters exist for the current function. 

• The current function returns a value which has a size greater than 4 bytes. 
(This causes a "result address" to be placed on the stack.) 

Reserving Space For "C" Variables 

After the instructions for setting up the stack frame, any automatic variables 
and any register variables that cannot be assigned to the SI register are 
allocated by decrementing the stack pointer (SP). No stack pointer 
adjustment instruction will be generated if there are no automatic variables or 
unassigned register variables. (Total local space is padded to a multiple of two 
bytes.) 

Pushing Data Segment (DS) Register 

(Large and compact memory models only). Following the allocation of 
automatics, if the memory model is "large" and the current function references 
any static data, the data segment (DS) register will be pushed on the stack and 
then loaded with a new segment paragraph number. This is to allow the 
DS-relative accesses within the current function to address the appropriate 
static data segment. This code for setting up a new DS-relative static data 
segment will never appear for the small and medium memory models, and 
does not appear for the large memory model when there is no static data 
associated with the current function. 
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Buffering Register Variable (SI) 

Next, the function prolog pushes the old register variable (SI) on the stack if 
SI has been allocated for use by the function as a register variable. Also, the 
compiler may use this register for an automatic regardless of whether or not it 
has been declared with the register storage class specifier (see the "Register 
Usage" section which follows). 

Buffering 8087 Floating Point Register Variables 

The last code in the function prolog saves floating point register variables 
ST(2) through ST(6). In general, it is more cost effective when saving several 
8087 registers to save the whole 8087 state instead of saving individual 
registers. Therefore, if the 8087 is being used (that is, if the "generate code for 
the 8087" option is on) and one or more floating point register variables are to 
be used by the function then the complete 8087 internal state is saved into a 
94-byte space on the stack. This is accomplished with an FSAVE instruction 
followed by an FLDCW instruction. The FLDCW instruction is necessary to 
propagate the previously set up 8087 control word into the reset 8087. (The 
FSAVE instruction also resets the 8087.) At function epilog the internal state 
of the 8087 is restored with instructions FSTCW and FRSTOR. Here, the 
FSTCW is required to propagate back any changes made to the 8087 control 
word while in this function. 

Observe that the 8087 status word is not propagated when 8087 register 
variables are saved. This is normally not a problem, except when exceptions 
are masked that are to be later unmasked and acted upon. These pending 
exceptions might not be retained outside of the function where they occur. 
This loss of "exceptions history" occurs only when the "generate code for the 
8087" option is on and floating point register variables are used. 

For interrupt routines, if the "generate code for the 8087" option is on the 
complete 8087 internal state is saved regardless of whether or not floating 
point register variables are used. Also, the 8087 control word is not 
propagated, so the interrupt routine writer must set up the control word 
before using the 8087. 

Accessing Parameters 

Each parameter's assembly symbol name is SET to that parameter's offset 
from the frame pointer. The value of these offsets differ from one stack model 
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to another. Refer to the "Stack Models" chapter for illustrations of the stack 
models. 

In the stack shown in figure 4-2, the offset of the first parameter will be 6 
(large memory model) if the value returned is 4 bytes or less. The offset of the 
first parameter will be 10 (large memory model) if the result size is greater 
than 4 bytes. For example, if "p" is the first parameter passed, the compiler 
may generate the following line in the assembly: 

%SET (S_p, 6) 

Parameters are accessed by using the symbol names relative to BP. Notice that 
when referencing a parameter, a percent sign (%) must precede the parameter 
name. For example: 

MOV SI, SS: WORD PTR [BP+%S_p+0] 

Shortening Parameters 

Unless function prototypes are used (see the "ANSI Extensions to C" section 
in the "C Compiler Overview" chapter), parameters of type char are widened 
to int when passed. Thus, any parameters formally declared to be of type char 
must be shortened from int. Since this shortening is defined to be by 
truncation, it is accomplished by simply using the parameter as if it were a 
char. (The parameter's offset needs no adjusting.) 

Similarly, float parameters are widened to double when passed. Thus, any 
formal float parameters must be shortened from their passed double form. To 
avoid problems when such parameters are optional, a float local variable is 
allocated, and the double value is converted to float and stored in the local 
variable. The formal parameter's offset from the frame pointer is then set to 
be that of the new local variable. 

An example of the widening and shortening of parameters is shown in figure 
4-4. The same example using function prototypes is shown in figure 4-5. 
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HPB1493-19303 8086 C Cross Compiler A. 04. 01 parmshrt.c 



;MKT:@(#) B1493-19303 A. 04. 01 8086 C CROSS COMPILER 



03May95 



Memory Model : large 



5PAGEWIDTH (230) 
$NOPAGING 

NAME "parmshrt" 
%DEFINE (MM_CHECK_) (MM_CHECK_L) 
%DEFINE (lib) (lib) 
%DEFINE (SS) (SS) 
%DEFINE (DS) (DS) 
%DEFINE (ALIGN) (WORD) 
%DEFINE (DALIGN) (WORD) 

prog_parmshrt SEGMENT %ALIGN PUBLIC 'CODE' 
%DEFINE (CodeSegment ) (prog_parmshrt ) 



_mam 



main ( ) 
{ 

PUBLIC 
ASSUME 
PROC 



_main 

CS : % Code Segment , DS : NOTHING 
FAR 



%SET (SAVE_ALL_NPX, 2) 



PUSH 

MOV 

SUB 

%SET (S_c, -6) 
%SET (S_f , -4) 

3 
4 
5 
6 

MOV 
CBW 
PUSH 
CALL 
POP 



BP 

BP, SP 
SP, 6 



char 
float 



f , 



char_f unct ( ) ; 
f loat_f unct ( ) ; 



char_f unct (c) ; 

AL, SS : BYTE PTR [BP+%S_c+0] 



AX 

FAR PTR _char_funct 

CX 

float_funct (f ) ; 
LES DI,SS:DWORD PTR [BP+%S_f+0] 

MOV DX,ES 
XCHG AX,DI 
SUB SP,8 
%lib SEGMENT WORD PUBLIC 'CODE' 
EXTRN F32_TO_F64_LM:FAR 
%lib ENDS 
CALL 
CALL 
ADD 
8 } 
f unctionExitl : 
MOV 
POP 

returnLabell : 
RET 

_main ENDP 



char widened to int. 



FAR PTR F32_TO_F64_LM - 
FAR PTR _float_funct 
SP, 8 



SP, BP 
BP 



float widened to double 



Figure 4-4. Widening and Shortening of Parameters 
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10 char char_f unct ( chr ) 

11 char 

12 { 
PUBLIC 
ASSUME 

_char_f unct 
%SET ( SAVE_ALL_ 

PUSH 

MOV 

%SET (S_chr, 6) 

13 

MOV 

14 

MOV 
15 } 
f unctionExit2 
POP 

returnLabel2 : 
RET 

_char_f unct 
16 



chr ; 




_char_f unct 




CS : %CodeSegment , DS : NOTHING 
PROC FAR 
NPX, 2) 

BP 

BP, SP 


int shortened to 
char (offset 
points to least 
significant byte 
of parameter.) 


chr = ' A' ; 

SS : BYTE PTR [BP+%S_chr+0 ] , 65 
return (chr) ; 
AL, 65 


BP 




ENDP 





17 
18 
19 



float float_f unct (fit) 
fit; 



float 
{ 

PUBLIC 
ASSUME 

_f loat_f unct 

%SET (SAVE_ALL_NPX, 2) 
PUSH BP 
MOV BP,SP 
SUB SP,4 

%SET (S_f It, -4) 

%SET (S_wide_paraml 



_f loat_f unct 

CS : % Code Segment , DS : NOTHING 
PROC FAR 



PUSH 
PUSH 
PUSH 
PUSH 



6) 

WORD PTR 
WORD PTR 
SS:WORD PTR 
SS:WORD PTR 



SS 
SS 



%lib 



SEGMENT WORD PUBLIC 



[BP + %S_ 
[BP + %S_ 
[BP + %S_ 
[BP + %S_ 
' CODE' 



wide_paraml + 0 + 6 ] 
wide_paraml+0+4 ] 
wide_paraml+0+2 ] 
wide_paraml+0 ] 



%lib 



20 



21 



EXTRN 
ENDS 
CALL 
MOV 
MOV 

MOV 
MOV 

LES 
MOV 
XCHG 
22 } 
f unctionExit3 : 
MOV 
POP 

returnLabel3 : 
RET 

_f loat_f unct 
prog_parmshrt 



F 6 4_TO_F 3 2_LM : FAR 

FAR PTR F64_TO_F32 
SS:WORD PTR [BP+%S_ 
SS:WORD PTR [BP+%S 
0; 



fit = 1 
SS:WORD PTR 
SS:WORD PTR 
return ( f It ) ; 
DI,SS:DWORD PTR 
DX, ES 
AX, DI 



SP, BP 
BP 



[BP + %S_ 
[BP + %S_ 



LM < 

f lt+0] , AX 
f lt+0+2] ,DX 

f lt+0] , 00H 

f lt+0+2] , 03F80H 



double shortened to float. 



[BP+%S_flt+0] 



ENDP 
ENDS 
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HPB1493-19303 8086 C Cross Compiler A. 04. 01 protypes.c 



;MKT:@(#) B1493-19303 A. 04. 01 8086 C CROSS COMPILER 

; Memory Model : large 

$PAGEWIDTH (230) 
$NOPAGING 

NAME "protypes" 
%DEFINE (MM_CHECK_) (MM_CHECK_L) 
%DEFINE (lib) (lib) 
%DEFINE (SS) (SS) 
%DEFINE (DS) (DS) 
%DEFINE (ALIGN) (WORD) 
%DEFINE (DALIGN) (WORD) 

prog_protypes SEGMENT %ALIGN PUBLIC 'CODE' 
%DEFINE (CodeSegment ) (prog_protypes ) 
1 main ( ) 



03May95 



_mam 



{ 

PUBLIC 
ASSUME 
PROC 



_main 

CS : % Code Segment , DS : NOTHING 
FAR 



%SET (SAVE_ALL_NPX, 2) 



PUSH 

MOV 

SUB 

%SET (S_c, -6) 
%SET (S_f , -4) 

3 
4 
5 



BP 

BP, SP 
SP, 6 



char 
float 



c, char_f unct (char) ; 
f, float_f unct ( float ) , 



6 




char_f unct (c) ; 




MOV 


AL, SS : BYTE PTR [BP+%S_c+0] 




PUSH 


AX 




CALL 


FAR PTR _char_funct 




POP 


CX 


7 




f loat_funct (f ) ; 




LES 


DI,SS:DWORD PTR [BP+%S_f+0 




PUSH 


ES 




PUSH 


DI 




CALL 


FAR PTR _float_funct 


o 


ADD 


SP, 4 


f unctionExitl 






MOV 


SP, BP 




POP 


BP 


returnLabell : 






RET 




main 


ENDP 




9 






10 


char 


char_f unct ( 


11 


char 


chr ) 



char no longer 
widened to int. 



float no longer 
widened to double. 



Figure 4-5. Function Prototype Parameter Passing 
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12 { 

PUBLIC 
ASSUME 
_char_f unct 
%SET (SAVE_ALL 
PUSH 
MOV 

%SET (S_chr, 6) 

13 



14 



MOV 



MOV 



15 } 
f unctionExit2 : 
POP 

returnLabel2 : 
RET 

_char_f unct 
16 



_char_f unct 

CS : %CodeSegment , DS : NOTHING 
PROC FAR 
NPX, 2) 
BP 

BP, SP 

chr = ' A' ; 

SS : BYTE PTR [BP+%S_chr+0 ] , 65 
return (chr) ; 
AL, 65 



BP 



17 
18 
19 



float 
float 
{ 

PUBLIC 
ASSUME 
_f loat_f unct 
%SET (SAVE_ALL 
PUSH 
MOV 

%SET (S_flt, 6) 

20 



ENDP 

f loat_f unct ( 
fit) 



21 



22 



MOV 
MOV 

LES 
MOV 
XCHG 
} 



functionExit3 : 
POP 

returnLabel3 : 
RET 

_f loat_f unct 
prog_protypes 
EXTRN 

mm_check 

DW 

mm_check 

END 



_f loat_f unct 

CS : % Code Segment , DS : NOTHING 
PROC FAR 
NPX, 2) 

BP 

BP, SP 

fit = 1.0; 

SS:WORD PTR [BP+%S_f lt+0 ] , 00H 

SS:WORD PTR [BP+%S_f lt+0+2 ] , 03F80H 
return (fit) ; 

DI,SS:DWORD PTR [BP + %S_f lt + 0 ] 
DX, ES 
AX, DI 



BP 



ENDP 
ENDS 

%MM_CHECK_: BYTE 
SEGMENT BYTE COMMON 
OFFSET %MM_CHECK_ 
ENDS 



Figure 4-5. Function Prototype Parameters (Cont'd) 
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Accessing Locals 

The last local (automatic) variable declared appears first on the stack. Each 
local variable's assembly symbol name is SET to that variable's offset from the 
frame pointer. For example, if "r" is the first local declared, and there are 20 
bytes of local variables, then the compiler generates the following line in the 
assembly: 

%SET (S_r, -20) 

Local variables are accessed using the symbol name relative to BP. Notice that 
when referencing a local (automatic) variable, a percent sign (%) must 
precede the variable name. For example: 

MOV SS:WORD PTR [BP+%S_r+0 ] , DX 

Using the Stack for Temporary Storage 

Code generated by the function's body may or may not use the stack for 
temporary storage of intermediate results. This temporary storage size is 
dynamic through the function, but has all been removed by the time the 
function exit code is executed. 

Function Results 

Function return values of one, two, three, or four bytes are returned in 
working registers AL, AX, DL-AX, or DX-AX respectively. Results greater in 
size are returned indirectly through a "result address" pointer pushed by the 
calling routine. This pointer may point to a static memory location, an 
automatic variable, or temporary space on the stack. 

Function Exit 

At function exit, if the 8087 state was saved, it is restored. If the register 
variable (SI) has been buffered it is popped. If the data segment register (DS) 
has been buffered and altered, it is popped. And finally, if there is a stack 
frame, it is removed by adjusting the stack pointer past the automatics (if any) 
and popping the old frame pointer back into BP. The function return itself 
pops the return address. The calling routine is responsible for incrementing 
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the stack pointer, popping the passed parameters, and, if necessary, removing 
the space reserved for structure function results. Function exit behavior may 
be modified by using the pragmas described in this chapter. 
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Register Usage 



Note This section applies only to C function calls. Run-time libraries invoked in 

compiler-generated code may use other conventions understood by the calling 
code. (See the "Run-Time Library Description" chapter.) 



For the small memory and medium models, registers AX, BX, CX, DX, and 
DI are reserved as working registers for use in holding intermediate values of 
calculations. For the large and compact memory models, the working registers 
include those registers used for the small memory model and additionally 
register ES. Function return values of one, two, three, or four bytes are 
returned in working registers AL, AX, DL-AX, or DX-AX respectively. 
Larger types are returned on the stack. Registers BP and SP are the frame 
pointer and stack pointers. 

For all memory models, the compiler will use the lower byte of registers AX, 
BX, CX, and DX (registers AL, BL, CL, and DL) to hold chars. The compiler 
also pairs up word registers in multiple combinations to create pseudo 32-bit 
registers for holding longs, floats, and additionally, pointers when large or 
compact memory model is in effect. For the small and medium memory 
model, these pseudo registers are in MSW-LSW order: DX-AX, AX-BX, 
CX-BX, DX-BX, AX-DI, CX-DI, and DX-DI. If the 'byte align data" 
compiler option is used, the register pair DL-AX is used for 24-bit data. The 
large and compact memory models include those pseudo registers used by the 
small memory model as well as ES-BX and ES-DI. All four memory models 
also include a 64-bit pseudo register CX-BX-DX-AX. 

Register Variable SI 

Register SI is allocated by the compiler for use as a register variable. For the 
small and medium memory model this register variable maybe either an 
integer or a pointer; for the large and compact memory model, it can only be 
an integer because a pointer will not fit. 
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Using the priorities listed below, the compiler allocates one of the following 
types of objects to register SI: 

1 The first variable (parameter or local) declared with register storage class. 

2 A local non-static or function variable, or the address of a static variable, 
according to frequency of occurrence of the variable's name in the 
function. 

Specific use of the auto storage class prevents a local variable from becoming a 
register variable. 

To better understand the allocation scheme, consider the following example. 
Suppose a local non-static variable appears just once in the function body. A 
parameter appears twice in the function body. Which gets the register? The 
local variable does because the parameter, which appears less than three times, 
has not "qualified" for consideration for frequency of occurrence. 

Now let us suppose that the parameter appears n times where n is three or 
greater. Suppose the local non-static variable appears n-1 times. Which gets 
the register? The parameter because it has "qualified" for consideration and 
has a greater number of occurrences. 

Passing Data 

For C functions, no registers are used to explicitly pass data to a called 
function. Data is passed implicitly by using segment registers (according to 
the memory model) to maintain segment bases across a call boundary. The 
following registers are used to explicitly pass data back to the caller: AL for 
8-bit data, AX for 16-bit data, DL-AX for 24-bit data, and the DX-AX pair for 
32-bit data. All other return data is passed back via the stack. No other 
registers are used explicitly for passing data back to the caller. 

The following registers must not be corrupted by a called routine (that is, the 
called routine must return with the same value sent by the caller): 

• CS, DS, and SS segment registers for all four models. 

• ES segment register for the small and medium memory model. 

• SP, BP, and SI registers for all four memory models. 

The compiler makes the following assumptions about segment registers, which 
affect whether a register will be reloaded or assumed to contain the needed 
value: 
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• CS does not change for the small and compact memory model. 

• DS, SS, and ES contain the same value and do not change for the small 
and medium memory model. 

• SS does not change for all four models. 

8087 Registers 

When using the "generate code for the 8087" option the compiler will use 8087 
registers ST(0), ST(1), and ST(7) as working registers. The remaining five 
8087 registers ST(2) through ST(6) are reserved for float and double register 
variables. 

At code startup (crtO or crtl) the 8087 is reset and its control word initialized. 
The 8087 NPX stack pointer (STP) is initialized to 0. STP can be from 0 to 7 
and determines which 8087 hardware register is actually at "top of stack". 
Normally the compiler operates with STP equal to 0. When an object is to be 
loaded into the 8087 the compiler may "push" the object onto the 8087 "top of 
stack", causing STP to become 7. The compiler will eventually "pop" this 
value, with STP returning to 0. This "pushing" and "popping" effectively moves 
objects through register ST(7). 

Registers ST(0) and ST(1) are general purpose working registers and are 
allowed to be either "empty" or contain a number, NaN, etc. Register ST(7) is 
a special purpose working register. The compiler expects that ST(7) will be 
"empty" except when the compiler is moving data through it. It is imperative 
that ST(7) be "empty" following in-line assembly code, or an 8087 "illegal 
operation" exception may occur. It is also required that in-line assembly code 
end with the 8087 NPX stack pointer (STP) in its original state (normally 0). 
In-line assembly code may leave registers ST(0) and ST(1) in any state. 
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Run-Time Error Checking 

Specifying the "generate run-time error checking" (-g) option causes the 
compiler to generate code for the following types of additional run-time error 
checking: 

• Dereferences of all NULL pointers and uninitialized automatic pointers 
are detected and reported. (Dereferencing is also called indirection; in 
other words, it is access to the object to which a pointer points.) This 
requires the initialization of automatic pointers at run-time with a value 
(-1) indicating they are uninitialized. Note that static variables are not 
initialized to the uninitialized pointer value, because the default value for 
static variables is zero. 

• Array references outside declaration index bounds are detected and 
reported. 

The "generate run-time error checking" option will override the "optimize" and 
"strip symbol table information" options. See the on-line man pages for more 
information on the compiler command line options. 



Memory Model Mismatch Checking 

Because the compiler supports four different memory models it is important 
to distinguish code generated using one memory model from that generated 
with the other. Program modules compiled with small memory model may not 
be linked with modules compiled with large memory model. An attempt to do 
so will result in a link-time "unresolved symbol" error with the "memory model 
check" symbol. 

Run-time library lib routines have different names from one memory model to 
the other. Small memory model routines end with "_S", compact memory 
model routines end with "_C", medium memory model routines end with "_M", 
and large memory model routines end with "_L". This guarantees that the 
wrong run-time library can never be accidentally linked to the user's code. 
Many routines can be used by two memory models; thus "_LM" routines can be 
used by the large or medium memory model. 
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Code from compiled libraries, such as libc and libm, and the user's C code is 
guaranteed to be linkable only with modules compiled with the same memory 
model. This memory model checking is accomplished with a "memory model 
check" symbol which is different for each memory model. They symbol is 
MM_CHECK_S for the small memory model, MM_CHECK_C for compact, 
MM_CHECK _M for medium, and MM_CHECK_L for large. The memory 
model checking symbol adds only two bytes to the length of a program because 
the data word that holds the symbol is placed in a COMMON segment. 

Figure 4-6 shows the assembly code which makes an external reference to the 
"memory model check" symbol. This symbol is defined by the startup code 
(crtO or crtl) in the environment library (env). Thus, crtO (or crtl) determines 
which memory model is expected to be in effect. 

HPB1493-19303 8086 C Cross Compiler A. 04. 01 mmcheck . c 

;MKT:@(#) B1493-19303 A. 04. 01 8086 C CROSS COMPILER 03May95 

; Memory Model: large 
i 

5PAGEWIDTH (230) 
$NOPAGING 

NAME "mmcheck" 
%DEFINE (MM_CHECK_) (MM_CHECK_L) 
%DEFINE (lib) (lib) 
%DEFINE (SS) (SS) 
%DEFINE (DS) (DS) 
%DEFINE (ALIGN) (WORD) 
%DEFINE (DALIGN) (WORD) 

prog_mmcheck SEGMENT %ALIGN PUBLIC 'CODE' 
%DEFINE (CodeSegment ) (prog_mmcheck) 

1 main ( ) 

2 ( 

PUBLIC _main 

ASSUME CS : % Code Segment , DS : NOTHING 
_main PROC FAR 
%SET (SAVE_ALL_NPX, 2) 

3 } 

f unctionExitl : 
returnLabell : 



RET 




_main ENDP 




prog_mmcheck 


ENDS 


EXTRN 


%MM_CHECK_: BYTE 


mm_check 


SEGMENT BYTE COMMON 


DW 


OFFSET %MM_CHECK_ 


mm_check 


ENDS 


END 





Figure 4-6. Memory Model Checking 
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Using Assembly Language in the C Source File 

The 8086/186 C compiler provides three mechanisms to embed assembly 
language instructions. Which one you choose depends on where you want the 
assembly language to appear and your purpose for including the assembly 
language instructions. The mechanisms are: 

• # pragma ASM and # pragma END_ASM 

• asm ('C_string') 

• # pragma FUNCTION_ENTRY "C_string", 

# pragma FUNCTION_EXIT "C_string", and 

# pragma FUNCTION_RETURN "C_string" 

The compiler changes the names of C variables and functions into assembly 
language symbols. If you know how the changed symbol names will appear in 
the generated assembly code, you may easily use C variables and functions in 
your embedded assembly code. (For more information on symbol names, see 
the "Symbol Names" section in this chapter.) 

When you embed assembly language, all assumptions about working registers 
for optimization purposes are forgotten. The register variable (SI), the frame 
pointer (BP), and the stack pointer (SP) are not buffered prior to embedded 
assembly language sections. You should buffer these registers if they will be 
used by your assembly code. 

Optimizations do not affect your embedded assembly code. 

None of these mechanisms are part of the ANSI standard, so programs which 
use embedded assembly language may not be portable to other compilers. 
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# pragma ASM 

# pragma END ASM 

Syntax: 

#pragma ASM 

(assembly language statement ( s ) ) 
#pragma END_ASM 

These two pragmas bracket a portion of inline assembly code. You may use 
these pragmas anywhere a C statement or external declaration can occur. Place 
the # pragma ASM before the beginning of your embedded assembly code and 
place the # pragma END_ASM after the code. 

The assembly instructions must conform to the format and syntax required by 
the HP B1449 assembler. The C compiler does not check the embedded 
assembly instructions for correctness. The compiler simply passes the assembly 
language statements, unchanged, to the assembler. You may, however, use the 
C preprocessor to alter embedded assembly language instructions. 



Example Figures 4-7, 4-8, and 4-9 give examples of using the # pragma ASM/END_ASM 

to embed assembly code in a C source file. 
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main ( ) 
{ 

printf ( "Starting interrupt test. \n") ; 
♦pragma ASM 

INT 33 ; Interrupt handler is at 00084H. 

#pragma END_ASM 

printf ( "Ending interrupt test. \n") ; 

} 



♦pragma ASM 

interrupt_table SEGMENT AT 8 ; Locate segment at 00080H. 

ORG 4 ;Org to 00084H. 

DD _interrupt_handler 
interrupt_table ENDS 
♦pragma END_ASM 



♦pragma INTERRUPT 

static void interrupt_handler ( ) 

{ 

printf ("An interrupt 33 has occurred . \n ") ; 

} 



Figure 4-7. # pragma ASM/EN D ASM Example 1 
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/* Example of embedded assembly language code when using large memory model. */ 

main ( ) 

{ 

auto int il, i2; 

11 = 1; 

12 = get_global ( ) ; 

/* Swap il and i2 but do it in assembly. */ 
♦pragma ASM 

MOV AX, [BP+%S_il] (Percent needed for auto or parameter. 

XCHG AX, [BP+%S_i2] 
MOV [BP+%S_il] , AX 

#pragma END_ASM 

printf("il = %d\ni2 = %d\n", il, i2); 



#pragma SEGMENT DATA=my_data 
int global_var = 1234; 
tpragma SEGMENT UNDO 

int get_global() 

{ 

register int reg_var; /* reg_var is held in register SI. */ 

fpragma ASM 

PUSH DS ; Save current data segment. 
MOV AX, SEG _global_var 

MOV DS,AX 

MOV SI,DS:WORD PTR _global_var ; Put it in reg_var. 

POP DS ; Restore data segment 

tpragma END_ASM 

return (reg_var) ; 

} 



Figure 4-8. # pragma ASM/EN D ASM Example 2 
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int *p; 
int i; 

main ( ) 
{ 

p = Si; /* Get address of i. */ 

i++; /* Increment i. */ 

printf ( "Using C: p = %p, i = %d\n",p,i); 



/* 


The following lines of assembly do the same thing as the lines 


*/ 


/* 


"p = Si;" and "i++;" in C. It illustrates the GROUP override 


*/ 


/* 


requirements when embedding in-line assembly for small memory 


*/ 


/* 


model. The compiler defines both %DS and %GRP to be the group 


*/ 


/* 


name "data_const" when using small memory model. The macros 


*/ 


/* 


could be replaced with "data_const" directly in this source but 


*/ 


/* 


this could mean incompatibility with future releases of the 


*/ 


/* 


compiler. For large memory model %DS is defined to be just 


*/ 


/* 


"DS"; %GRP is not defined. Because %DS is available for both 


*/ 


/* 


memory models it can be used to write assembly code that will 


*/ 


/* 


work for both small and large memory models. Note the "INC..." 


*/ 


/* 


line of assembly. 


*/ 



♦pragma ASM 

#ifdef SMALL_MODEL/* SMALL memory model */ 

MOV %DS:WORD PTR _p, OFFSET %GRP:_i 
#else/* LARGE memory model */ 

;Compiler has set up DS register to access p and i DS-relative. 

MOV DS:WORD PTR _p, OFFSET _i 

MOV DS:WORD PTR _p[2],SEG _i 
#endif 

INC %DS:WORD PTR _i;For both small and large model. 
#pragma END_ASM 

printf ( "Using assembly: p = %p, i = %d\n",p,i); 

} 



Figure 4-9. # pragma ASM/EN D ASM Example 3 
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asm ('C_string") 

Syntax: 

asm ( "C_string") 

The quotes are part of the C_string argument and the two preceding 
underscores are required to meet ANSI name space requirements. 

The asm function is another way to embed assembly code. It differs from the 

# pragma ASM/END_ASM pair in two ways: 

• # pragma ASM/END_ASM brackets a section of inline assembly code. In 
contrast, the assembly language instructions are contained in a "C_string" 
argument to the asm function. 

• # pragma ASM/END_ASM may appear either inside or outside of a 

function body. Because asm is syntactically a function call, it may only 

appear inside a function bodyjust as any other function call must. 

The asm function has some advantages over the # pragma ASM/END_ASM 

mechanism. First, this function can be part of a macro definition which means 
you may define a macro that contains embedded assembly language. The 

# pragma ASM/END_ASM pair cannot be used to do this. Second, for single 

assembly instructions, the asm function is more expedient because it 

requires just the function call on a single line. 

The "C_string" argument is a character string containing one or more lines of 
assembly code. (The quotes are part of the argument.) It must contain white 
space so that when the string is output to the generated assembly code, it will 
conform to the format and syntax required by the HP B1449 Assembler. The C 
compiler does not check the C_string for correctness. The compiler simply 
outputs the string to the assembly code. 



Example Figure 4-10 gives an example of using the asm function. 
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/* Example of embedded assembly code when using large memory model. */ 

tdefine SAVE_DS asm("\tPUSH DS ; Save current data segment."); 

tdefine RESTORE_DS asm("\tPOP DS (Restore data segment"); 

main ( ) 
{ 

auto int il, i2; 

11 = 1; 

12 = get_global ( ) ; 

/* Swap il and i2 but do it in assembly. */ 

/* Notice the "\t" white space that must appear in order to conform */ 
/* to the Assembler requirement that instructions cannot begin in */ 
/* column 1. Spaces or a tab character would also have worked. */ 
/* Notice also that there is no need to terminate the string with */ 
/* a newline. Also, more than one assembly line may be handled */ 
/* by a single asm() function by separating the lines with a "\n".*/ 

asm("\tMOV AX, [BP + %S_il] (Percent needed for auto or parameter."); 

asm("\tXCHG AX, [BP+%S_i2] \n\tMOV [BP+%S_i 1 ] , AX" ) ; 

printf("il = %d\ni2 = %d\n", il, i2); 

} 

tpragma SEGMENT DATA=my_data 
int global_var = 1234; 
tpragma SEGMENT UNDO 

int get_global() 
{ 

register int reg_var; /* reg_var is held in register SI. */ 

/* Notice the use of cpp macros to specify assembly code. */ 
SAVE_DS 

asm("\tMOV AX, SEG _global_var " ) ; 

asm("\tMOV DS,AX"); 

asm("\tMOV SI,DS:WORD PTR _global_var ;Put it in reg_var."); 

RESTORE_DS 

return (reg_var) ; 

} 



Figure 4-10. asm Function Embedded Assembly 
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# pragma FUNCTION ENTRY, 

# pragma FUNCTION_EXIT, 

# pragma FUNCTION RETURN 



Syntax: 

#pragma FUNCTION_ENTRY "C_string" 
#pragma FUNCTION_EXIT "C_string" 
#pragma FUNCTION_RETURN "C_string" 

The third mechanism is # pragma FUNCTION_ENTRY /EXIT /RETURN. 

These pragmas are not a pair like # pragma ASM/END_ASM. They maybe 
used independently of each other or they may be used together. 

• pragma FUNCTION_ENTRY may be used to insert assembly language 
instructions into function entry code. Similarly, # pragma FUNCTION_EXIT 
and # pragma FUNCTION_RETURN maybe used to insert assembly language 
instructions into function exit code. Neither # pragma ASM/END_ASM nor 

the asm function is able to place embedded assembly in the function entry 

or exit code. The embedded code is placed as follows: 

• # pragma FUNCTION_ENTRY places the embedded assembly code 
immediately after the label generated from the function name. Because 
the embedded assembly occurs before any function entry code, you can 
modify the way a function is entered. 

• # pragma FUNCTION_EXIT places the embedded assembly immediately 
before the function return label. That is, it follows the function exit code, 
but precedes the function return. (Some NOPs may appear between the 
embedded assembly code and the return label.) This pragma gives you the 
flexibility to control function return and also allows you to perform extra 
instructions before function return. 

• # pragma FUNCTION_RETURN places the embedded assembly 
immediately after the function return label. Use this pragma if you want to 
use your own function return code. For example, you might want to trap 
to a debugging routine. 

Remember, you may use # pragma FUNCTION_ENTRY, FUNCTION_EXIT, 

and FUNCTION_RETURN by themselves, or you may use all of them together 
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Two limitations apply to these pragmas: 

• # pragma FUNCTION_ENTRY, # pragma FUNCTION_EXIT, and 

# pragma FUNCTION_RETURN may only appear outside of a function 
body. 

• # pragma FUNCTION_ENTRY, # pragma FUNCTION_EXIT, and 

# pragma FUNCTION_RETURN must precede the function they are to 
affect. They are in effect only for the immediately following function and 
no other. 

These pragmas take a "C_string" argument. (The quotes are part of the 

argument and no parentheses surround the argument.) As with the asm 

function, the "C_string" argument is a character string containing assembly 
language instructions. It must contain white space and newlines ("\n") so that 
when the string is output to the generated assembly code, it will conform to 
the format and syntax required by the HP B1449 assembler. The C compiler 
does not check the C_string for correctness. The compiler simply outputs the 
string to the assembly code. 



Example Figure 4-11 gives an example of using # pragma FUNCTION_EXIT along with 

# pragma INTERRUPT (discussed in the "Embedded Systems Considerations" 
chapter) to cause an interrupt service routine to trap back to the operating 
system instead of allowing it to terminate with an IRET instruction as it would 
if # pragma PNTERRUPT were used alone. When this routine enters its 
function exit code, it will do the cleanup of the stack and other chores in 
preparation of the IRET. But because the # pragma FUNCTION_EXIT code 
causes the routine to trap back to the operating system, it will never execute 
the IRET. 
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♦pragma INTERRUPT 

♦pragma FDNCTION_EXIT "\tINT 2 ; Trap back to operating system." 

static void interrupt_handler ( ) 
{ 

printf("An interrupt 33 has occurred . \n 11 ) ; 

} 

/* Interrupt routine exits via "INT 2" instead of "IRET". */ 



Figure 4-1 1 . # pragma FUNCTION_EXIT 
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Assembly Language in Macros 

To use assembly language in a macro, use the asm function. The # pragma 

mechanism does not work in a macro. 

When you write the macro, remember the following suggestions: 

• Use asm, not one of the pragmas. 

• Do not use macro parameters in the assemly code. The C preprocessor 
does not expand names inside the quotation marks. 

• Use spaces and tabs (entered as At") to place "white space" in the assembly 
code. 

• If you need to place more than one line of assembly language in the 

macro, either use an asm statement for each line or place a "\n" between 

lines. The C preprocessor will place the entire macro on one line, then 
the compiler will change the "\n" to a newline when generating the 
assembly code. 

• Be careful about changing the values of C variables (side effects) in the 
macro. You may wish to include the names of such variables in the name 
of the macro. 

• You can examine the generated assembly code by compiling with 
cc8086 -SL and looking at the .O file. If you need to understand how 
the C preprocessor affected the code, use cc8086 -E. 

Assembly Language and the Small Memory Model 

When writing embedded assembly code in a C source file that is expected to be 
compiled using small memory model certain considerations must be made. 
For small memory model the compiler places all segments containing data or 
constants (data, idata, udata, heap, userstack, and const) into an assembly 
language group called data_const. The compiler then accesses objects in the 
data_const group "group-relative" instead of "segment-relative". For large 
memory model the compiler does "segment-relative" accesses to all data and 
constant objects because no segments are in a group. Objects contained in 
program segments (functions, for example) are always accessed (or called) 
"segment-relative", regardless of the memory model. 

Figure 4-7 can be compiled using either memory model. It does not contain 
memory model dependent pragmas or assembly code. 
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Figure 4-8 can be compiled only for large memory model because it does 
contain a SEGMENT pragma and also contains memory model dependent 
assembly code. If compiled with small memory model the SEGMENT pragma 
would simply be warned at and ignored when encountered. However, the 
assembly instructions accessing _global_var would not produce functional 
code. Specifically, 1) the line "MOV AX,SEG _global_var" would load the AX 
register with the segment paragraph number of _global_var instead of the 
group paragraph number as it should, and 2) the line "MOV SI,DS:WORD 
PTR _global_var" may access _global_var as if it were not contained in a group 
and therefore go to the wrong place in memory. 

Figure 4-9 demonstrates how to write assembly code that functions correctly 
no matter which memory model is used. At the beginning of the assembly file 
it produces, the compiler defines an assembly language macro DS to be either 
DS for large memory model (nothing needs to be changed), or data_const for 
small memory model. Thereafter, %DS: can be used instead of DS: to specify 
a "segment-relative" override for large memory model and at the same time a 
"group-relative" override for small memory model. For small memory model 
only, the compiler also defines another macro GRP to be data_const. This 
second macro allows embedded, "small memory model only" assembly code to 
reference the group name independently of the group name created by the 
compiler. Figure 4-9 shows its use as well. 
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5 



Optimizations 

Description of optimizations performed by the compiler. 
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The 8086/186 C compiler performs many optimizations automatically; there is 
also an "optimize" command line option (-O) to cause peephole optimization, 
time or space optimization, and other compile-time costly optimizations. This 
chapter first describes the optimizations which are always performed; next, it 
describes the optimizations which occur as a result of the "optimize" command 
line option. 



Universal Optimizations 

The 8086/186 C compiler automatically performs many optimizations on C 
programs. Several of the most notable types of optimizations are listed below 
and described in this section. 

• Constant Folding. 

• Expression Simplification. 

• Operation Simplification (involves multiplies, divides, and mods by 
powers of two). 

• Optimizing Expressions in a Logical Context (involves expressions which 
contain logical operators). 

• Loop Construct Optimization. 

• Switch Statement Optimization. 

• Automatic Allocation of Register Variables. 

The compiler may do many specific things for each type of optimization. The 
descriptions which follow contain examples to illustrate the kinds of things 
which are done for each type of optimization; they do not show every specific 
optimization performed by the compiler. 



Note In the general examples which follow, E represents any expression, C 

represents any constant, !0 represents a constant with a non-zero value, and 
other operator symbols are their C equivalents. 
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Constant Folding 

Whenever an expression contains operations made on constants, the compiler 
combines the constants to form a single constant. By folding constants, the 
compiler can eliminate the code which would otherwise be generated to 
perform the operations. A general and specific example of constant folding is 
shown below. 



CI *C2-C3/C4 


=> 


C5 


i= 4*3-10/2; 


=> 


i= 7; 
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Constant Folding Across Expressions 



The compiler will rearrange integer expressions to fold constants. 



(El + CI) + ( E2+ C2) 


=> 


(El + E2) + (CI + C2) 


(El *C1) *(E2*C2) 


=> 


(El *E2) *(C1 *C2) 


(El + CI) *C2 


=> 


(El *C2)+ (CI *C2) 


(El << CI) *(E2*C2) 


=> 


(El * E2) * ((2 C1 ) * C2) 


i= (x*3+ 1) *3+ 2 


=> 


i= x*9+ 5 



Maintaining Order of Evaluation 

Parentheses force grouping (prevent constant folding) of floating-point 
expressions. The unary plus (+ ) operator maybe used to force grouping of 
arithmetic expressions. The unary plus operator may not be used to force 
grouping of pointer expressions. For example: 



i = x+ 4.141+ y+ 2.067+ 3.287; 


=> 


i= x+ y+ 9.495; 


i= x+ 4.141+ (y+ 2.067)+ 3.287; 




i= x + +(y+ 2.067)+ 7.428; 


i= x+ 4.141+ + (y+ 2.067)+ 3.287; 


=> 


i= x + + (y+ 2.067) + 7.428; 



Expression Simplification 

The compiler will simplify expressions, if possible, by using the basic laws, 
identities, and definitions of conditional, logical, bitwise, and arithmetic 
operations. Some examples of expressions which get simplified follow. 

Conditional: 



0?E1 : 


E2 


=> 


E2 


!0?E1 


:E2 


=> 


El 
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Logical: 



E &&0 




=> 


0 (unless E has side effects; then E,0) 


E 1 1 0 




=> 


E 


El && !E2 




=> 


!(!E1 1 1 E2) 


Bitwise: 


E & 0 




=> 


0 (unless E has side effects; then E,0) 


E 1 0 




=> 


E 


E A 0 




=> 


E 


E << 0 




=> 


E 


Arithmetic: 


E + 0 




=> 


E 


-El -(-E2) 




=> 


E2-E1 


E * 0 




=> 


0 (unless E has side effects; then E,0) 


E * 1 




=> 


E 


E/-1 




=> 


-E 


E % 1 




=> 


0 (unless E has side effects; then E,0) 




Operation Simplification 






Multiplications (whether explicit or as a result of scaling an array index), 
divisions, and mods of integral types by constants which equal powers of two 
can be simplified to bitwise operations which are shorter and faster. Generally: 


E * (2 C ) 




=> 


E<< C 


E/(2 C ) 




=> 


E >> C 


E % (2 C ) 




=> 


E & (2 C - 1) 
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Optimizing Expressions in a Logical Context 

When expressions containing logical operators are used in a logical context 
(for example, to yield a "true" or "false" in a control flow statement test 
expression), the compiler will generate code which evaluates the expression 
piece by piece. For example, suppose the test expression for an if statement is 
two expressions ANDed together. The compiler generates code which 
evaluates the first expression and branches out if it is "false" (if, at run-time, 
the first expression is "false", the second expression will not be evaluated). The 
compiler also generates code to evaluate the second expression in case the first 
is "true". The code generated as a result of this optimization is smaller and 
faster. Several "pseudo code" examples of optimizations on expressions in a 
logical context are shown below. 



if (0) goto label 


=> 


(Nothing.) 


if (!0) goto label 


=> 


goto label 


if (El 1 1 E2) goto label 


=> 


if (El) goto label 






if (E2) goto label 


if (El &&E2) goto label 


=> 


if (!E1) goto skip 






if (E2) goto label 






skip: 



Loop Construct Optimization 

The compiler places the evaluation of a loop construct's test expression at the 
end of the loop to avoid the execution of a "goto" at each loop iteration. A 
"goto" is generated to branch to the test for the first iteration. However, if the 
compiler can determine that the loop will execute at least once, the "goto" can 
be optimized out. Whenever the test expression becomes "false", execution 
simply "falls through". 
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The loop construct optimization can be generally expressed as follows. 



while (E) { statements } 


=> 


goto end 






beginning: 






{ statements } 






end: if (E) goto beginning 


for (i = 0; i < 10;) 




i= 0 


{ statements } 




beginning: 






{ statements } 






if (i < 10) goto beginning 



Switch Statement Optimization 

If there is code associated with at least 25% of the cases in a switch statement, 
the compiler will generate a jump table to access the code associated with each 
case. If less than 25% of the cases have associated code, the compiler will 
generate a hybrid binary/linear search to access the cases. The linear search 
can be up to four items long, otherwise a binary test is performed. 

Automatic Allocation of Register Variables 

Operating on variables which reside in registers is faster and more efficient 
than operating on variables in memory. The 8086/186 C compiler will 
automatically allocate variables to registers even in the absence of the register 
storage class specifier. Note that the presence of the auto storage class 
specifier prevents this optimization. For more information on the algorithm 
used by the compiler to allocate these variables, see the "Register Usage" 
section in the "Compiler Generated Assembly Code" chapter. 

String Coalescing 

When the compiler finds identical string constants, it stores them at a single 
memory location. In the following example, both stringl and string2 will point 
to the same memory location containing the string "abcde": 

char *stringl, *string2; 
stringl = "abcde"; 
string2 = "abcde"; 
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Only string constants allocated by the compiler are coalesced. For example, 
the following strings will not be coalesced because the user, rather than the 
compiler, is allocating the storage: 

char string3[8] = "abcde"; 
char string4[8] = "abcde"; 



Note Trying to change the value of a string constant may cause unwanted side 

effects. 



The compiler treats string literals as constants. Do not attempt to change the 
contents of a string which has been defined as a string literal. Be especially 
careful if you are using character pointers. For example, the following 
statements will change the value of both stringl and string2 to "abXde": 

char *stringl, *string2; 
stringl = "abcde"; 
string2 = "abcde"; 

* (stringl + 2) = ' X' ; 

The compiler will not warn you about this. 
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1 struct test { 

2 int a, b, c, d, e, f ; 

3 } x, y; 
4 

5 main ( ) 

6 { 
0000 
0000 

0000 _main 
0000 



0000 


IE 






0001 


B8 


00 


00 


0004 


8E 


D8 

y = 


= X 


0006 


BA 


00 


00 


0009 


B8 


00 


00 


OOOC 


83 


EC 


OC 


000F 


96 






0010 


8C 


DB 




0012 


8E 


DA 




0014 


8B 


FC 




0016 


8C 


Dl 




0018 


8E 


CI 




001A 


B9 


06 


00 


001D 


FC 






001E 


F3 


A5 




0020 


8E 


DB 




0022 


8B 


F0 




0024 


BA 


00 


00 


0027 


BF 


oc 


00 


002A 


8E 


C2 




002C 


B9 


06 


00 


002F 


FC 






0030 








0030 


58 






0031 


AB 






0032 


E2 


FC 





OPTIMIZED FOR SPACE (Default). 



PUBLIC 


_main 




ASSUME 


CS 


:prog_space, DS : data 


PROC 


FAR 




PUSH 


DS 






MOV 


AX 


, data 




MOV 


DS 


, AX 




MOV 


DX 


, SEC _x 




MOV 


AX 


, OFFSET 


_x+0 


SUB 


SP 


, 12 




XCHG 


AX 


f SI 




MOV 


BX 


,DS 




MOV 


DS 


, DX 




MOV 


DI 


, SP 




MOV 


CX 


, SS 




MOV 


ES 


, CX 




MOV 


CX 


, 6 




CLD 








REP MOVSW 






MOV 


DS 


, BX 




MOV 


SI 


, AX 




MOV 


DX 


, SEC _y 




MOV 


DI 


, OFFSET 


_y+0 


MOV 


ES 


, DX 




MOV 


CX 


, 6 




CLD 








POP 


AX 






STOSW 








LOOP 


L0 







struct test 
int 

} x, y; 

main ( ) 
{ 



a, b, c, d, e, f ; 



OPTIMIZED FOR TIME. (More bytes 
used to accomplish structure assignment, 
but code executes faster.) 



0000 








PUBLIC 


_main 


0000 








ASSUME 


CS:prog_ 


0000 








_main PROC 


FAR 


0000 












0000 


IE 






PUSH 


DS 


0001 


B8 


00 00 


R 


MOV 


AX, data 


0004 


8E 


D8 

y = x; 




MOV 


DS, AX 



Figure 5-1 . Example of Time vs. Space Optimization 
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0006 


BA 


00 


00 R 


MOV 


DX 


, SEC _x 


0009 


B8 


00 


00 R 


MOV 


AX 


, OFFSET 


oooc 


83 


EC 


OC 


SUB 


SP 


, 12 


000F 


96 






XCHG 


AX 


, SI 


0010 


8C 


DB 




MOV 


BX 


, DS 


0012 


8E 


DA 




MOV 


DS 


, DX 


0014 


8B 


FC 




MOV 


Dl 


, SP 


0016 


8C 


Dl 




MOV 


cx 


, ss 


0018 


8E 


CI 




MOV 


ES 


, CX 


001A 


B9 


06 


00 


MOV 


CX 


, 6 


001D 


FC 






CLD 






001E 


F3 


A5 




REP 


MOVSW 




0020 


8E 


DB 




MOV 


DS 


, BX 


0022 


8B 


F0 




MOV 


SI 


, AX 


0024 


BA 


00 


00 R 


MOV 


DX 


, SEC _y 


0027 


BF 


oc 


00 R 


MOV 


Dl 


, OFFSET 


002A 


8E 


C2 




MOV 


ES 


, DX 


002C 


8B 


F4 




MOV 


SI 


, SP 


002E 


8C 


DA 




MOV 


DX 


,DS 


0030 


8C 


Dl 




MOV 


CX 


, SS 


0032 


8E 


D9 




MOV 


DS 


, CX 


0034 


B9 


06 


00 


MOV 


CX 


, 6 


0037 


FC 






CLD 






0038 


F3 


A5 




REP 


MOVSW 




003A 


83 


C4 


oc 


ADD 


SP 


, 12 


003D 


8E 


DA 




MOV 


DS 


, DX 


003F 


8B 


F0 




MOV 


SI 


, AX 



8 } 



Figure 5-1 . Example of Time vs. Space Optimization 



The Optimize Option 

The "optimize" command line option (-O) causes the compiler to use a more 
exhaustive algorithm in an attempt to generate locally optimal code; it also 
causes the compiler to run the peephole assembly code optimizer (unless the 
"generate run-time error checking code" option is also specified, in which case 
the "optimize" command line option is ignored). 

You may find it easier to debug your code if you do not use the "optimize" 
option. Optimizations may make it difficult to follow the program flow. After 
the code is executing properly, use optimization to improve execution speed or 
to shrink the size of the executable code. 
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Time vs. Space Optimization 

By default, the -O option causes the generated code to be optimized for space. 
That is, the compiler tries to generate as few bytes of code as possible (even, 
occasionally, at the expense of execution speed). However, if optimizing for 
time is more important (in other words, the generated code should execute as 
fast as possible), you can append the "time" option to the "optimize" option 
(-OT). Optimizing for time will cause the compiler to use more space if 
machine cycles can be saved. The listings in figure 5-1 give an example of a 
time vs. space trade-off. 

Maintaining Debug Code 

The compiler normally generates code which makes the resulting programs 
easier to debug with an HP emulator or simulator. This debug code includes: 

1 Generation of no-operation (NOP) instructions preceding all labels. This 
provides unique addresses for all labels. 

2 Buffering of the frame pointer on the stack at function entry and 
restoration of the frame pointer at function exit, even when this is known 
to be unnecessary. 

When the "optimize" option is specified, this debug code is optimized out. 
However, if you wish the compiler to generate debug code and perform the 
other optimizations, use the "generate debug code" option with the "optimize" 
option. See the on-line man pages for more information on the compiler 
command line options. 
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Peephole Optimization 

The peephole optimizer, which is run when the "optimize" command line 
option is specified, adds another pass to the compilation process. The 
peephole optimizer examines the assembly language instructions generated by 
the compiler and performs the optimizations described in the following 
subsections. 

Branch (Jump) Shortening 

Perhaps the most common peephole optimization is branch shortening. 
Neither the compiler (by itself) nor the assembler is capable of determining 
the distance of a forward branch. Consequently, NEAR jumps with 16-bit 
displacements are generated by default. 

The peephole optimizer, on the other hand, is capable of determining the 
distance of forward branches, and it will replace NEAR jump instructions with 
SHORT jump instructions wherever possible. 

Tail Merging 

A tail is a sequence of instructions before an unconditional jump. 

When two blocks of code end in identical branches, the peephole optimizer 
checks if the blocks have the same tail statements. If the blocks do have 
identical tail statements, the peephole optimizer will replace the first tail with 
a "goto" the second. For example: 





=> 




{ tail 1 } 


=> 


goto sametail 


goto label 


=> 






=> 


sametail: 


{ tail 2 } (Same as tail 1.) 


=> 


{ tail 2} 


goto label 


=> 


goto label 




=> 




label: 


=> 


label: 



Tail merging can take place wherever tails are found, including if-then-else 
and switch statements. The compiler does not limit the size of tails that can be 
merged. 
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If tail merging would cause an additional branch to be executed, it is not 
performed when "optimize for time" is specified. 

Redundant Register Load Elimination 



When the peephole optimizer detects that a register is being loaded with a 
value it already contains, the second load is eliminated. (Compare to 
"Strength Reduction" below.) 



MOV BX,DS: WORD PTR_ 


_i[0] 




MOV BX,DS: WORD PTR_ 


_i[0] 


; This instruction is removed. 



Redundant Jump Elimination 

When one jump occurs immediately after another jump, the two jumps are 
combined to form a single jump. Note that this optimization is performed on 
the generated assembly code, but a C code equivalent example would be the 
following: 



if (x= = y) goto aaa; 


=> 


if (x= = y) goto bbb; 


aaa:goto bbb 




aaa: goto bbb; 


bbb: 




bbb: 



Unreachable Code Elimination 



As compilers normally generate code, they can produce assembly instructions 
which will never get executed. The peephole optimizer can recognize 
unreachable assembly instructions and remove them. 

Strength Reduction 

Strength reduction refers to optimizations which can be made due to the 
optimizer's ability to remember the contents of registers. For example, the 
compiler may generate code to move a variable into one register, and later 
generate code to move the same variable into another register. The peephole 
optimizer can replace the second move with a move from the first register to 
the second (which is shorter and faster). One to two bytes will be saved by the 
example strength reduction optimization shown below. 



117 



Chapter 5: Optimizations 

The Optimize Option 



MOV BX,DS: WORD PTR_ 


_i[0] 


=> 


MOV BX,DS: WORD PTR_i[0] 


MOV AX,DS: WORD PTR_ 


_i[0] 


=> 


MOV AX,BX 



Redundant Scale Calculation Elimination 



The array index in C must be scaled to its corresponding value in assembly 
code. For example: In an array of integers, the index value must be doubled. 
The peephole optimizer removes any redundant scaling. In the code shown 
below, the second scaling calculation would be removed: 



MOV 


BX,DS: 


WORD PTR_i[0] 


SHL 


BX,1 




MOV 


BX,DS: 


WORD PTR_i[0] 


SHL 


BX,1 





Before the second scaling calculation, the optimizer verifies that the contents 
of BX and _i have not been changed between the two scaling operations. 



Effect of volatile Data on Peephole Optimizations 

Any function that includes a volatile declaration or which follows any volatile 
declaration in a file will not have "data motion" optimizations performed on it. 
Data motion optimizations include redundant load elimination, strength 
reduction optimizations, and redundant scale calculation elimination. 

These optimizations account for considerably less than half of the space 
savings and roughly half of the speed savings that the peephole optimizer is 
capable of. 

Branch shortening and branch structure simplification optimizations (tail 
merging, redundant jump elimination, and unreachable code elimination) are 
unaffected by volatile data. 

Function Entry and Exit 

The -O option also affects function entry and exit code. Whenever a called 
function has no parameters, no automatics, and returns a result whose size is 
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four bytes or less, the instructions which are used to push the old stack frame 
pointer at function entry and restore the frame pointer on exit are not 
generated. 

What to do when optimization causes problems 

Occasionally, the peephole optimizer can make incorrect assumptions, 
resulting in code that does not execute properly. Use the -Wo,-m 
command-line option to eliminate some of the risky optimizations (especially 
common sub-expression optimizations). If the code still doesn't execute 
properly, you may need to avoid the -O optimizations. 
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6 



Embedded Systems Considerations 

Issues to consider when using the 8086/186 C compiler to generate code for 
your target system. 
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Execution Environments 

The compiler cannot know the design of your target system. Therefore, all 
high-level functions and library routines depend on environment-dependent 
libraries to supply low-level hooks into the target execution environment. 

The environment-dependent routines which are supplied with the compiler 
allow programs produced by the compiler to execute in an emulator. The 
supplied routines also support the debugger/simulator. Use these files as 
examples to create your own environment-dependent routines. We expect that 
you will need to modify the supplied files. You must use your own knowledge 
of your target system to decide what changes must be made. 
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Common problems when compiling for an 
emulator 

If you plan to execute your program in an emulator environment, follow these 
guidelines: 

• Copy emulation configuration files (*.EA) from the environment directory 
to a local directory prior to using. 

• U se # pragma SEGMENT DATA= idata to specify the segment for 
"initialized" data external declarations when using the -d option (separate 
initialized and uninitialized data). 

Loading supplied emulation configuration files 

Symptoms: In the emulator, one of the two supplied emulation 
configuration files is loaded from the directory 

/usr/hp64000/env/hp< emul_env> and the following error message appears: 

ERROR: Could not create 

/usr/hp 64000/ env/hp<emul_env>/ ioconf ig . EB 

Description: There are two forms of emulator configuration files. The first 
form (.EA), which is supplied, is an ASCII file. The second form (.EB), which 
is created from the ASCII file by the emulator, is a binary file. This binary file 
is not portable between versions of HP 64000 emulators and therefore not 
supplied. 

When loading a configuration file, the emulator attempts to create the binary 
version of the file if one does not already exist. This binary file is created in 
the same directory as the ASCII file. The directory which contains the 
supplied configuration files is not meant to be modified and is write-protected. 
In order to use the supplied configuration file, it must first be copied to a local 
(writable) directory. 

Using the "-d" option 

Symptoms: During compilation, cc8086 displays the following warning: 

warning- Extern ' variable_name' assumed to be in UDATA. 
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Description: The "Separate Initialized and Uninitialized Data" option (-d) 
causes the compiler to place static variable definitions with initializers in 
segment idata by default, and static variable definitions without initializers in 
segment udata by default. When an external declaration of a static variable is 
encountered the compiler assumes the external variable is uninitialized, places 
the external declaration in segment udata, and issues a warning regarding this 
assumption. It is very important that if the external is instead an initialized 
variable that this warning be heeded and the external declaration placed in the 
proper segment (idata). To do this, place a # pragma SEGMENT 
DATA= idata directive before the initialized variable's external declaration 
and a # pragma SEGMENT UNDO following it. The second pragma merely 
"undoes" the first pragma. See the "Embedded Systems" chapter for more 
details on using these pragmas. 

Using embedded assembly code with small memory model 

Description: For the small memory model, the compiler places all data 
objects in an assembly language group called data_const. When writing 
embedded assembly code, group-relative accesses MUST be performed instead 
of segment-relative accesses to static variables and constants. Using 
segment-relative accesses can cause non-functional code to be produced. 



Memory Models 

Memory models determine how both segments are to be mapped into memory 
and the size of pointers. The 8086/186 C compiler provides four memory 
models, small, compact, medium, and large. The small memory model uses 
fixed segments and 16-bit pointers. The compact memory model provides one 
or more data segments and one code segment. The medium memory model 
uses one or more code segments and one data segment. The large memory 
model provides a flexible number of non-fixed segments and uses 32-bit 
pointers. Throughout a program, a single memory model must be used; code 
modules compiled with different memory models cannot be linked together. 



124 



Chapter 6: Embedded Systems Considerations 

Memory Models 

Small memory model 

The small memory model has two physical segments which never change. One 
is a code segment (CS register does not change). The other is a combined 
microprocessor stack and DS-relative static data group called data_const. (DS, 
SS, and ES registers are identical and do not change.) This group contains all 
the data, stack, heap, and constant type segments. This group is placed into a 
single physical segment at link time. Data and constants are accessed 
group-relative. 

There are no ES-relative static data segments in this model. Both the function 
and data pointer sizes are 16 bits. Pointer subtraction between function and 
data pointers will yield unknown results. 

Segment groups and classes are discussed in greater detail in your linker 
manual. 

Large memory model 

The large memory model may have one or more code segments (CS register 
may change), one independent stack segment (SS register does not change), 
zero or one DS-relative static data segment for each C function (DS register 
may change), and zero or more ES-relative static data segments (ES register 
may change). Both function and data pointer sizes are 32 bits. 

Except for comparisons between two pointers, pointer arithmetic is performed 
only on the lower 16 bits (the OFFSET part of the SEGMENT:OFFSET 
address). Operations to compare two pointers are performed using the 
complete logical address; no translation to a physical address is done. 

Functions are considered to be FAR and are called as such (except when a 
static function is encountered and the user has specified the compiler option 
which says that static functions are to be NEAR). 

The last defined static data segment preceding a function is accessed 
DS-relative. (See # pragma SEGMENT and # pragma DS.) All other static 
data segments are accessed ES-relative within that function. 



Note Only one static data segment can be DS-relative per function, but that 

segment can be different for each function. 
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Medium Memory Model 

The medium memory model may have one or more code segments (the CS 
register may change) and one data segment (the DS, SS, and ES registers are 
identical and do not change). The function pointer size is 32 bits, and the data 
pointer size is 16 bits. 

Compact Memory Model 

The compact memory model has one fixed code segment (the CS register does 
not change) and one or more data segments (the DS, SS, and ES registers are 
not identical and may change). The function pointer size is 16 bits, and the 
data pointer size is 32 bits. 
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Segment Names 

Segment names are used by the linker/loader to locate program code and data 
at the addresses appropriate for the target system environment. Code 
generated by the compiler is placed in relocatable program segments as 
follows: 

• Executable code is placed in the PROG segment (by default, named either 
prog_basename when using the largeor medium memory model, or prog 
when using the small or compact memory model). 

• Static variables are placed in the DATA segment (named data by default). 

• Constants and string literals are placed in the CONST segment (named 
const by default). 

When declaring external data, it is important that the declaration be placed in 
the segment where the data actually resides. If this is not done, a run-time 
error may occur when the wrong segment base is used for accessing an external. 

All code generated by the compiler is placed in segments with the class name 
"CODE". Thus the complete name of the default PROG segment is 
prog_basename/CODE. 

If there are multiple declarations for the same symbol within a single file, the 
compiler checks that the segment in which the symbol is declared is the same 
in all cases. 

Segment name defaults 

For large and medium memory model, the compiler allows more than one user 
program segment. To facilitate easy use of the compiler when user code 
exceeds 64K bytes (the maximum that can be placed in a single segment), the 
default PROG segment name is based, in part, on the C source filename. Thus, 
with large and medium memory model the default PROG segment name is of 
the form prog_basename where basename is the C source file name with the 
".c" suffix removed and any illegal characters (for a segment name) changed to 
underscore (_). 
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When using the small and compact memory model, the PROG segment name 
is always prog. Since the SEGMENT pragma is not valid for small memory 
model (only one user program segment is allowed) the user cannot change this 
segment name. 

The DATA segment name defaults to data. When the "separate initialized 
data and uninitialized data" option is used, DATA is replaced with ID ATA 
and UDATA which default respectively to idata and udata. 

The CONST segment name defaults to const. 

Like the PROG segment name, DATA, IDATA, UDATA, and CONST 
segment names cannot be altered from their defaults when using small and 
compact memory model. When using large and medium memory model, these 
segment names can be changed with a SEGMENT pragma in the C source. 

# pragma SEGMENT 

Syntax: 

tpragma SEGMENT [PROG=pname] [DATA=dname] [CONST=cname] 

#pragma SEGMENT [PROG=address] [DATA=address] [CONST=address] 

#pragma SEGMENT [PROG=pname] [UDATA=udname] [IDATA=idname] [CONST=cname] 

#pragma SEGMENT [PROG=address] [UDATA=address] [IDATA=address] [CONST=address] 

#pragma SEGMENT UNDO 



Note This pragma is only valid for the large, medium, and compact memory model. 

It is warned and ignored if it is used with the small memory model. 



Description 

The first form of this pragma causes the program, static data, and static 
constant information to be placed in segments named pname, dname, and 
cname respectively until the next SEGMENT pragma is encountered. The 
linker also expects to find external data in these named segments. 

In the second form, 20-bit physical addresses are given in place of the segment 
names causing the subsequent information to be ORG'd starting at the given 
address. The segment name associated with an ORG'd segment is of the form 
orghexaddress, where hexaddress is the physical address of the segment. For 
example, segment org00012345H is located at 0x12345. 
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When absolute addresses are used, all information (program, data, or 
constant) to be ORG'd must immediately follow the # pragma SEGMENT 
line and come prior to any information (program, data, or constant) which is 
output in another named or ORG'd segment. For example: 

#pragma SEGMENT DATA=0xl000 
int i, j, k; 
const int 1; 
int m, n, o; 

will cause an error since constant integer "1" is output in another segment 
(const) and since integers "m, n, o" also need to be ORG'd as they are data. 
Corrected this becomes: 

#pragma SEGMENT DATA=0xl000 
int i, j, k; 
int m, n, o; 
const int 1; 

Other cases that cause information to be put out in new segments include 
extern definitions and string literals. 

The third and fourth forms listed are the same as the first two forms, but with 
ID ATA and UDATA substituted for DATA. These forms make sense only in 
the presence of the "separate initialized and uninitialized data" option that 
forces separation of explicitly initialized data from implicitly initialized data 
(or uninitialized data with the "uninitialized data" option). Non-constant, 
static data items explicitly initialized by means of a C initializer go into the 
ID ATA named segment. Non-constant, static data items, not explicitly 
initialized by means of a C initializer, go into the UDATA named segment. 
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The absolute addresses and segment names maybe intermixed for the three 
different information types (program, static data, static constant) in the same 
SEGMENT pragma. If the target segment is not specified for one of the 
information types, then it remains unchanged. 

In the absence of a DS pragma, the DATA segment (or UDATA segment 
when using "separate initialized and uninitialized data" option) in effect at 
function entry is the default segment for DS-relative data accesses. (See below 
for information on the DS pragma.) 

The last form, # pragma SEGMENT UNDO, "undoes" the effect of the 
immediately preceding SEGMENT directive. That is, it restores the name (or 
address) of any segment renamed (or ORG'd) in the last directive. This form is 
useful at the end of # include files to restore the segment environment which 
existed prior to the # include file. (Include files must contain SEGMENT 
directives to define the segments that externs are in.) 

This compiler places all code in the class 'CODE'. No other class names are 
supported. 

The SEGMENT pragma must be placed outside a function body. 



Note # pragma SEGMENT UNDO is implemented by a one-level-deep stack. That 

is, only the most recent SEGMENT pragma maybe "undone" or, said another 
way, two # pragma SEGMENT UNDOs in a row will not undo two SEGMENT 
pragmas. This is of particular importance when an include file further includes 
other files. Since include files will generally surround their extern declarations 
with a SEGMENT-SEGMENT UNDO pair, care must be taken not to put an 
include inside of this pair as it will result logically in two "UNDO"s in a row. 
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# pragma DS 

Syntax: 

#pragma DS segmentName 



Note This pragma is only valid for the large and compact memory model. It is 

warned and ignored if it is used with the small and medium memory model. 



Description 

This pragma specifies that all subsequent functions should arrange to access 
any data in segment segmentName, rather than the default of the current 
DATA (or UDATA) segment name, using DS-relative addressing. (See the 
SEGMENT pragma regarding default segment names.) If subsequent functions 
access any static data in segment segmentName, their preambles load DS with 
segmentName and use it in accesses. The effect of this is that once a DS 
pragma is used, the DS-relative segment name is fixed until another DS 
pragma is encountered. 



RAM and ROM Considerations 

This section addresses special considerations of loading your programs into 
RAM and ROM environments. 

The C language specifies that, without explicit initialization, static (C static or 
extern) variables will be initialized to zero. Declarator initializers allow you to 
specify initial values other than zero. The following subsections discuss how 
these variables are initialized in different environments. 

No initialized RAM data 

There is an "uninitialized data" option for the compiler which prevents 
initialization to zero of all static variables which have no explicit initialization. 
Normally, these static variables are specified by the C language to be 
initialized to zero. 



131 



Chapter 6: Embedded Systems Considerations 

RAM and ROM Considerations 

The "uninitialized data" option also causes warning messages to be printed 
whenever static initializers are used in non-constant declarations. Observe that 
this option does not prevent the generation of "initialized data" when the user 
explicitly initializes a static (C static or extern) variable. By using this option 
you can verify that your program contains no variables requiring initialization. 

The "uninitialized data" option cannot check for the use of a static variable 
which has not been assigned a value (although the compiler generates 
warnings occasionally), so make sure your programs do not assume an 
initialized value. 

RAM data initialized from mass storage 

Programs executed in operating systems, in emulation environments, or in 
simulation environments have a "load time" where initialization can occur. 
The initial values, or default values of zero, for static variables are therefore 
written to RAM at load time. 

To facilitate optimal load time initialization of static data, a command line 
option has been provided to separate explicitly initialized data from 
uninitialized data (or data initialized to zero by default) into different named 
segments. By default, these segments are named idata and udata, but these 
names can be changed by using # pragma SEGMENT (see above). 

The value of this "separate initialized and uninitialized data" option is that it 
allows the loader to load initialized static data contiguously into RAM from 
the idata segment. Also, locations in the udata segment can be set to zero in 
an efficient, contiguous manner, if uninitialized data is to be given default 
initialization. 

The use of the "separate initialized from uninitialized" option together with 
the "uninitialized data" option (described above) supports emulation of an 
environment with a load time (for initializing explicitly initialized static data) 
which does not initialize uninitialized data to zero. When used together, the 
compiler does not warn on explicit initializations of non-constant static data, 
but places such data in segment idata (by default). Static data which is not 
explicitly initialized is reserved space in segment udata (by default), but is not 
initialized to zero at emulation/simulation load time. 
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RAM data initialized from ROM 

Unlike environments with mass storage, such as in operating systems or 
emulators, embedded environments have no "load time" and therefore cannot 
have load time initialization. As an example, when a target system is powered 
up, the contents of RAM data locations are not defined. However, the C 
language allows for a "prior to execution" initialization of static variables. To 
accomplish this initialization, the program's start-up code (crtO or crtl) can 
invoke a run time routine (_initdata()) to copy initial value data from ROM to 
RAM for these variables. The "initial value data" ROM tables which 
_initdata() reads are placed in a special series of segments. These segments are 
named ??DATA1, ??DATA2, etc. in segment class ??INIT. The segment class is 
used when referencing the segments in the linker command file. The number 
of segments actually used depends on how much space is needed for the tables. 

The default linker command files which are shipped with the compiler are 
configured such that the "initial value data" tables are not constructed and the 
run time initialization of static variables is not performed. Only minor 
modification of the linker command file is needed for the tables to be built by 
the linker and the _initdata() routine to be called from crtO (or crtl). 

Where to load constants 

Symbols declared with the const type modifier are considered to be ROM 
locations and are initialized by definition (small memory model differs in this 
regard, see the next subsection for more detail). For RAM/ROM embedded 
systems, both program and constants will ultimately reside in ROM and 
therefore the default segments prog and const contain ROMable information. 
In contrast, segments which hold program variables are not ROMable, but 
instead must be placed in RAM. 

RAM and ROM for small memory model 

With the small memory model, constants will be placed in a segment named 
const, and static data will be placed in a segment named data (idata or udata if 
the "separate initialized and uninitialized data" option is on). These four 
segments (const, data, idata, udata) plus the stack and heap segments 
(userstack, heap) are placed by the compiler in a group named data_const. 
The total size of this group, after linking, must be no more than 64K bytes; all 
segments in the group are linked to become a single physical segment. 
Therefore, although it is possible to position the const segment to be placed in 
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ROM, there must be RAM nearby in the address space to hold the other 
non-constant segments in the group. If the embedded environment is such that 
RAM and ROM are are too distant (size of data_const would become greater 
than 64K bytes) then segment const must be placed in RAM and initialized at 
either load time, if it exists, or at run time. Initialization of constants in RAM 
is done identically to that for "initialized data"; the assembly code produced by 
the compiler for allocating a constant is the same as that for allocating an 
"initialized data" variable. 

In summary, for small memory model, constants can be placed in ROM if 
there is RAM nearby to hold data. Otherwise constants must be placed in 
RAM, along with the data, and then initialized at either load time (emulator, 
simulator, or operating system environment) or at run time (embedded 
environment). 



Placement of External Declarations 

The compiler expects that all external data or constant declarations be 
explicitly placed in the same named segment in which the data or constant is 
defined (where storage is allocated). For example, if a static variable int xis 
defined in one file to be in DATA segment my_datal, then any extern int x 
declaration MUST be placed in segment my_datal. Failure to place external 
delcarations in their correct segments may result in non-functional code. The 
compiler uses this segment information to determine if it can or cannot 
perform a DS-relative access on a given variable or constant. 

With small memory model, because the segment names are predefined and not 
alterable by the user, externals are handled properly without the use of 
SEGMENT pragmas. 

Care must be taken when declaring external, initialized data when the 
"separate initialized and uninitialized data" option is in effect under large 
memory model. With this option in effect, initialized data definitions will be 
placed in segment idata by default (no SEGMENT pragma). However, with 
this same option, all external data declarations will be placed in segment udata 
by default. The compiler cannot know whether an external variable is 
initialized or uninitialized and therefore assumes it to be uninitialized and 
chooses the UDATA default segment name (udata). The compiler warns 
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when it makes this assumption. But because this assumption is wrong 
(external initialized variables are really in idata), incorrect code will result. 

It is imperative that when using the "separate initialized and uninitialized 
data" option all external declarations of initialized data be placed in the 
correct segment as shown in the following example. Note that DATA must be 
used, instead of IDATA or UDATA, to tell the compiler where an external is 
located. 



File: main.c 



#pragma SEGMENT DATA=idata 
extern int abc; 
#pragma SEGMENT UNDO 



/* Tell compiler "abc" is in segment "idata 



♦pragma SEGMENT DATA=udata 
extern int def; 
#pragma SEGMENT UNDO 



/* Tell compiler "def" is in segment "udata 



main ( ) 



abc++; 
def = abc; 



File: ext_data.c 



int abc=123; 
int def; 



/* "abc" is allocated space in segment "idata 
/* "def" is allocated space in segment "udata 



*/ 
*/ 
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The 'Volatile" Type Modifier 

The volatile type modifier is used in declarations to specify that an object's 
value may change in ways unknown to the compiler. A volatile type modifier 
makes the compiler access an object literally, as specified in C statements. 
Literal interpretations of C statements can be important in programs which 
are closely tied to hardware such as memory mapped I/O devices or device 
drivers. The volatile type modifier is necessary because optimizations can take 
short-cuts, using methods which differ from the literal interpretation but 
which yield the same result. 

The listings shown in figure 6-1 give an example of the effect given by the 
volatile type modifier. The top listing shows code in which the assignment of 
"io_port" to "secondValue" has been optimized into a "MOV AX,SI" 
instruction which does not actually read "io_port" (whose value may have 
changed since its assignment to "firstValue"). The bottom listing shows the 
"io_port" variable declared with the volatile type modifier. Notice that the 
assignment of "io_port" to "secondValue" does not get optimized. 

For the user who wants a controlled way of toggling an address line, it is 
guaranteed that a simple assignment to a volatile variable which has a size 
equal to the data bus width of the target processor will cause exactly one write. 
An access of such a variable will cause exactly one read. For example: 

*p = (char *) 0x12340005; /* 0x12340005 is logical address of 

I/O port. 0x12345 is physical 
address of I/O port. */ 



/* Exactly one write to address 0x12345. */ 
/* Exactly one read of address 0x12345. */ 

A pointer-to-volatile cannot be assigned to a pointer-to-non-volatile without a 
cast. 



Note If the 'byte align data" option is on, short and int variables maybe accessed 

with two reads or writes instead of just one. 



volatile char 



main ( ) 
{ 

*P = 0; 
*p; 

} 



136 



Chapter 6: Embedded Systems Considerations 

The "volatile" Type Modifier 



1 


int io_port; 


2 






3 


main ( ) 




4 


{ 






PUBLIC 


_main 




ASSUME 


CS : %CodeSegment, DS : data 


_main 


PROC 


FAR 


%SET (SAVE_ALL_NPX, 2) 




PUSH 


BP 




MOV 


BP, SP 




SUB 


SP, 4 




PUSH 


DS 




MOV 


AX, data 




MOV 


DS, AX 




PUSH 


SI 



; S_f irstValue is in register SI 
%SET (S_secondValue, -4 ) 
%SET (S_tmp, -2) 

5 
6 
7 



int firstValue, secondValue, tmp; 



10 





firstValue = io_port; 


OPTIMIZATION 


MOV 


SI,%DS:WORD PTR _io_port[0] 


PERFORMED 


MOV 


secondValue = io port; 


AX, S I ■< ' 




MOV 


SS:WORD PTR [BP+%S_secondValue+0 ] , AX 






tmp = firstValue; 




MOV 
} 


SS:WORD PTR [BP+%S_tmp+0 ] , S I 





volatile int io_port; 



1 
2 

3 main ( ) 

4 { 

PUBLIC _main 

ASSUME CS : %CodeSegment, DS : data 
_main PROC FAR 
%SET (SAVE_ALL_NPX, 2) 



PUSH BP 

MOV BP,SP 

SUB SP,4 

PUSH DS 

MOV AX, data 

MOV DS,AX 

PUSH SI 
: S_f irstValue is in register SI. 
=SET (S_secondValue, -4 ) 
fcSET (S_tmp, -2) 

int firstValue, secondValue, 



5 




6 




7 




8 


MOV 




MOV 




MOV 


9 






MOV 



tmp; 



10 



firstValue = io_port; 
SI,%DS:WORD PTR _io_port[0] 
secondValue = io_port; 
AX,%DS:WORD PTR _io_port[0] 
SS:WORD PTR [BP+%S_secondValue+0 ] 
tmp = firstValue; 
SS:WORD PTR [BP+%S_tmp+0 ] , SI 



NO OPTIMIZATION 
PERFORMED 



Figure 6-1 . 'Volatile" Type Modifier Example 
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Reentrant Code 

Reentrant code is code that can be interrupted during its execution and 
re-invoked by subsequent calls any number of times. A nonreentrant routine 
might, for example, operate on static data or external variables; if this routine 
is interrupted and called from somewhere else, the data it was originally 
operating on might be destroyed. Interrupt handlers and other routines which 
maybe interrupted and called again must be reentrant. 

The 8086/186 C compiler generates reentrant code. 

Nonreentrant library routines 

Most of the library routines which have been shipped with the compiler are 
reentrant. However, some of the libraries are not reentrant; they are listed 
below. 

Table 6-1 . Nonreentrant Library Routines 



assert 


free 


malloc 


rewind 


atexit 


freopen 


open 


scanf 


calloc 


fscanf 


printf 


setbuf 


close 


fseek 


putc 


setvbuf 


fclose 


fsetpos 


putchar 


srand 


fflush 


ftell 


puts 


strtok 


fgetc 


fwrite 


rand 


strtol 


fgetpos 


getc 


read 


ungetc 


fgets 


getchar 


realloc 


unlink 


fopen 


gets 


remove 


vfprintf 


fprintf 


lseek 




vprintf 


fputc 






write 


fputs 








fread 









Nonreentrant routines should not be called from interrupt handlers or other 
reentrant routines. 

Some libraries use the global symbol errno. Note that the value of errno can be 
overwritten in a multitasking or reentrant environment. 
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Implementing Functions as Interrupt Routines 

Interrupt routines are not intended to return values. Therefore, the type 
specifier void must be used to declare functions which you wish to implement 
as interrupt routines. The INTERRUPT pragma is used to specify that a 
function should be implemented as an interrupt routine. 



# pragma INTERRUPT 

This pragma specifies that the next encountered function be implemented as 
an interrupt routine. This means that all working registers are saved at 
function entry (plus any register variables which have been allocated), no 
parameter passing or returned result is allowed, and a return from interrupt is 
generated at the return point. 

If you are using assembly language code, remember that registers which are 
not used by the compiler as working registers or as register variables are not 
saved at function entry. See page 87 for a list of the compiler's working 
registers. 

Note that only the next encountered function is affected-not subsequent 
functions. 

The INTERRUPT pragma maybe used anyplace a C external declaration may. 
An example of a function implemented as an interrupt routine is shown below. 

tpragma INTERRUPT 

void int_routine ( ) 
{ 

} 



Loading the vector address 

Using the INTERRUPT pragma will cause all registers to be pushed onto the 
stack upon function entry, and a return from interrupt instruction is generated 
for function exit. However, you must make sure that the address of the 
function is loaded into the vector table. For example, integer divide-by-zero 
interrupts are handled by an environment-dependent file which is 
automatically linked in. Its source (div_by_0.c) contains a vector table which 
maybe modified to contain the address of your interrupt handler written in C. 
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In your own target system, it will be easiest to implement your vector table in 
C. For example, if you had implemented one routine totally in assembly 
language and named it "_asm_int_routine", you could declare your vector table 
and initialize it with: 

extern void asm_int_routine ( ) ; 

tpragma SEGMENT DATA=0x00 

void ( *vectorTable [ ] ) 0 = {. . ., asm_int_routine, . . ., 

int_routine, . . . } ; 

#pragma SEGMENT UNDO 
#pragma INTERRUPT 

void int_routine ( ) { 



Note When using small memory model, the vector table must be coded in assembly 

in order to specify both the segments and offsets of the interrupt handlers. See 
the figure in the "Compiler Generated Assembly Code" chapter for an example. 



Eliminating I/O 

Your embedded system may well have no file I/O capability. If this is the case, 
you can specify a linker command file which avoids the overhead of initializing 
emulation simulated I/O buffers for stdin, stdout, and stderr. See the 
description of cc8086 in the on-line man page. 
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7 



Libraries 

Descriptions of the run-time and support libraries. 
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Four varieties of libraries are provided with the 8086/186 C compiler. Each of 
these libraries comes in four versions: small memory model, compact memory 
model, medium memory model, and large memory model. Four versions are 
provided because you cannot mix memory models within a program. All code 
must be compiled and linked with the same memory model option. 

A check is done at link-time to ensure that all libraries and user -written code 
have been compiled using the same memory model. This feature eliminates 
code defects due to mixing the memory models. These defects could be stack 
misalignment, use of garbage data, and incompatibility of code or data sizes. 
These code defects would be very hard to find. 

A separate version of the math library is provided for use with the 8087. The 
cc80186 compiler shares the cc8086 libraries. 

The four varieties of libraries are: 

• Environment libraries which contain environment-dependent routines, 
such as exit( ), open(), sbrkf ), etc. See the "Environment Dependent 
Routines" chapter for full details. 

• Run-time libraries which contain routines required to do real number 
arithmetic, initializations, run-time debug checks, etc. 

• Support libraries which contain C functions such as fopenf), getchar(), 
malloc(),printf(), etc. 

• Math libraries which contain C functions such as exp( ),floor(), sin(), etc. 

A group of .h include files are also provided for use with the various libraries. 

The names of the various libraries and the segment names used to locate them 
by the linker are given below. The names of the libraries for the four memory 
models are the same, but the directories where they reside on your computer 
are different. 
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Table 7-1 . Library Names 



Library 


Library 
Name 


Large Memory Model 
Segment (PROG, DATA) 


Small Memory Model 
Segment (PROG, DATA) 


Environment 


env.a 


pti v/rODF pn vdata 

wll Y/ V- V./ 1 — ' 1 — i , V, 1 1 \ U III 11 , 

userstack, heap 


r>ro?/CODE data 
userstack, heap 


Run-time 


lib.a 


lib/CODE, libdata 


prog/CODE, data 


Run-time 

(8087) 


lib87.a 


lib/CODE, libdata 


prog/CODE, data 


Support 


libc.a 


libc/CODE, libcdata 


prog/CODE, data 


Math 


libm.a 


libm/CODE 


prog/CODE 


Math (8087) 


libm87.a 


libm/CODE 


prog/CODE 
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Run-Time Library Routines 

The run-time library, lib.a or lib87.a, contains routines used at run-time by 
the compiler-generated code. The calls to these routines are placed in the 
assembly code file by the compiler in place of generated assembly code (in-line 
code). The reasons for using library calls instead of generating in-line code 
vary from conserving space to minimizing repetition of in-line code to 
maintenance considerations (the same reasons C functions are used). 

The run-time libraries maybe called from compiler-generated code and 
assembly code (including embedded assembly code within the C source). Also, 
it should be possible to replace any or most of the library routines with your 
own routines. 

The names of all run-time library routines end in _S for small memory model 
libraries, _C for compact memory model libraries, _M for medium memory 
model libraries, and _L for large memory model libraries. This is to guarantee 
that a library routine from one memory model will never be accidentally linked 
to a call for the other memory model. 

The names of all run-time library routines end in JSC for small and compact 
memory model libraries, and in _LM for large and medium memory model 
libraries. 

See appendices "Small Memory Model Run-time Routines" and "Large 
Memory Model Run-Time Routines" for descriptions of the interface and 
functionality of all run-time library routines. 
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Support Library and Math Library Routines 

In general, the implementation of the support library routines is likely to 
deviate subtly from the standard due to environment dependencies. Where 
possible, the sources for these environment-dependent routines (which are 
customized to HP development environments) are provided as part of the 
compiler product (see the chapters describing "Environment Dependent 
Routines"). 



Library Routines Not Provided 

Several "standard" C library routines are not provided with the 8086/186 C 
compiler. 

• General Utilities. The < stdlib.h> functions abort, getenv, and system are 

not supported. 

• Input/Output. The < stdio.h> definitions L_tmpnam, FILENAME_MAX, 
and TMP_MAX, as well as the rename, tmpfile, and tmpnam routines, are 
not supported. 

• Signal Handling. The < signal.h> routines are not provided because of 
their extreme environment dependencies. 

• Date and Time. The < time.h> routines are not provided because of their 
extreme environment dependencies. 
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Include (Header) Files 

The following is a list of include files which are shipped with the compiler: 



assert.h 
ctype.h 

errno.h 
float.h 

fp_control.h 



limits .h 
locale.h 

math.h 

memory.h 
setjmp.h 

simio.h 

stdarg.h 



Defines the macro assert. 

Defines the "character classification" macros (e.g., 
isalnum, isalpha, etc.). 

Declares errno and macros used to test errno. 

Describes the IEEE single- and double -precision 
floating-point representations and contains definitions 
of the limiting values of floating-point types. 

Declares the floating-point error functions. This 
header file also defines the macros which can be used as 
arguments to the _set_fp_control function, or to check 
the return value of the _get_fp_status function. 

Contains definitions of the limiting values for integral 
types. 

Declares the setlocale and localeconv functions and 
defines the lconv structure. Also defines the categories 
which the functions can change. 

Declares the standard math library routines and 
HUGE_VAL. 

Declares sbrk and _getmem. 

Defines the jmpjbuf type and declares the setjmp and 
longjmp functions. 

Declares the simulated I/O functions and companion 
macros. 

Provides the va_list type and the macros which are used 
to access variable-length argument lists, va_start, 
va_arg, and va_end. For a description of the variable 
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argument list macros, see the entry for "va_list" in this 
chapter. 



stddef.h 



Defines the ptrdiff_t, size_t, and wchar_t types and the 
NULL null pointer constant. This header file also 
defines the offsetof macro. 



stdio.h 



Declares all the functions that handle input and output. 
This header file also defines the FILE type, buffering 
macros, file positioning macros, the maximum number 
of open files, and buffer size macros. 



stdlib.h 



Defines the types div_t and ldiv_t, and also the macros 
EXIT_SUCCESS, EXIT_FAILURE, RANDJMAX, and 
MB_CUR_MAX. This header file also declares standard 
library functions. 



string.h 



Declares the character string and memory operations. 
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List of All Library Routines 



The following table lists all of the library routines shipped with this compiler. 

An asterisk (*) in the Index column means that you can find a description of 
the routine in this manual by looking in the index. 

The routines not marked with an asterisk are not described in this manual. 
These routines are run-time routines or subroutines used by the libraries. You 
should not use these undocumented routines in your programs because they 
are likely to be changed or even deleted in future versions of the compiler. 



Index 


Definition name 


Library 


* 


ADD_F32A_«ze 


lib 
lib87 


* 


ADD_F32B_s7ze 


lib 
lib87 


* 


ADD_F32C_«ze 


lib 
lib87 


* 


ADD_F64A_s7ze 


lib 
lib87 


* 


ADD_F64B_iize 


lib 
lib87 


* 


ADD_F64C_iize 


lib 
lib87 


* 


DEC_F32_57ze 


lib 
lib87 


* 


DEC_F64_iiz<? 


lib 
lib87 


* 


DIV_F32A_«ze 


lib 
lib87 


* 


DIV_F32B_«ze 


lib 
lib87 


* 


DIV_F32C_iize 


lib 
lib87 



Index 


Definition name 


Library 


* 


DIV_F64A_«ze 


lib 
lib87 


* 


DIV_F64B_s;ze 


lib 
lib87 


* 


DIV_F64C_si'ze 


lib 
lib87 


* 


DIV_I32A_«ze 


lib 
lib87 


* 


DIV_I32B_«ze 


lib 
lib87 


* 


DIV_UI32A_5/ze 


lib 
lib87 


* 


DIV_UI32B_«ze 


lib 
lib87 




DPADD_iize 


lib 
lib87 




DPDIV_iize 


lib 
lib87 




DPMUL_5/ze 


lib 
lib87 




DPRDIV_5i'ze 


lib 
lib87 
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Index 


Definition name 


Library 


* 


EQUAL_F32_s/ze 


lib 
lib87 


* 


EQUAL_F64_«ze 


lib 
lib87 




Err_Handler 


lib 
lib87 


* 


F32_TO_F64_«ze 


lib 
lib87 


* 


F32_TO_I16_«ze 


lib 
lib87 


* 


F32_TO_I32_5ize 


lib 
lib87 


* 


F32_TO_UI16_«ze 


lib 
lib87 


* 


F32_TO_UI32_«ze 


lib 
lib87 


* 


F64_TO_F32_iize 


lib 
lib87 


* 


F64_TO_I16_«z<? 


lib 
lib87 


* 


F64_TO_I32_5ize 


lib 
lib87 


* 


F64_TO_UI16_«ze 


lib 
lib87 


* 


F64_TO_UI32_«ze 


lib 
lib87 


* 


FAULT_I16_«ze 


lib 
lib87 


* 


FAULT_I32_iize 


lib 
lib87 


* 


FAULT_I8_«ze 


lib 
lib87 



Index 


Definition name 


Library 


* 


FAULT_PTR_size 


lib 
lib87 


* 


FAULT_UI16_«ze 


lib 
lib87 


* 


FAULT_UI32_iize 


lib 
lib87 


* 


FAULT_UI8_«ze 


lib 
lib87 




FPADD_iize 


lib 
lib87 




FPDIV_«ze 


lib 
lib87 




FPMUL_mz<? 


lib 
lib87 




FPRDIV_iize 


lib 
lib87 


* 


I16_TO_F32_5ize 


lib 
lib87 


* 


I16_TO_F64_«ze 


lib 
lib87 


* 


I32_TO_F32_«ze 


lib 
lib87 


* 


I32_TO_F64_«ze 


lib 
lib87 


* 


INC_F32_«ze 


lib 
lib87 


* 


INC_F64_«ze 


lib 
lib87 


* 


LESS_EQ_F32_«ze 


lib 
lib87 


* 


LESS_EQ_F64_«ze 


lib 
lib87 
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Index 


Definition name 


Library 


* 


LESS_F32_5i'ze 


lib 
lib87 


* 


LESS_F64_«ze 


lib 
lib87 




L_l_IO_check_loop 


env 




L_2_IO_exit_loop 


env 


* 


MOD_I32A_iize 


lib 

11DO / 


* 


MOD_I32B_«ze 


lib 

UDo / 


* 


MOD_UI32A_«ze 


lib 

11DO / 


* 


MOD_UI32B_«z<? 


lib 

llDo / 




MONITOR_MESSAGE 


env 


* 


MUL_F32A_«ze 


lib 
lib87 


* 


MUL_F32B_5i'ze 


lib 
lib87 


* 


MUL_F32C_5i'ze 


lib 
lib87 


* 


MUL_F64A_«ze 


lib 
lib87 


* 


MUL_F64B_iize 


lib 
lib87 


* 


MUL_F64C_5ize 


lib 
lib87 


* 


MUL_I32A_«ze 


lib 
lib87 


* 


MUL_I32B_siz<? 


lib 
lib87 



Index 


Definition name 


Library 


* 


SUB_F32A_«ze 


lib 
lib87 


* 


SUB_F32B_iize 


lib 
lib87 


* 


SUB_F32C_«z<? 


lib 

UDo / 


* 


SUB_F64A_5/ze 


lib 

UDo / 


* 


SUB_F64B_iize 


lib 

llDo / 


* 


SUB_F64C_mz<? 


lib 

UDo / 




TOP_OF_STACK 


env 




UI16_TO_F32_iize 


lib 

UDo / 


* 


UI16_TO_F64_5ize 


lib 
lib87 


* 


UI32_TO_F32_ii'ze 


lib 
lib87 


* 


UI32_TO_F64_«ze 


lib 

llDo / 




USER_ENTRY 


env 




USR_STACK 


env 




XEnv_86_except 


env 




_TOP_OF_HEAP 


env 




_USR_HEAP 


env 


* 


fflush 


libc 


* 


assert 


libc 
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Index 


Definition name 


Library 




bufendtab 


env 




bufsync 


libc 


* 


clear_fp_status 


lib 

HK87 


* 


ctype 


libc 




_dbl_to_str 


libc 


* 


display_message 


env 




doprnt 


libc 




do scan 


libc 




errjiandler 


lib 

HK87 


* 


error_msg 


env 




exec_funcs 


libc 


* 


exit 


env 




exit_msg 


env 




_filbuf 


libc 




findbuf 


libc 




findiop 


libc 




_flsbuf 


libc 


* 


fp_control 


lib 


* 


fp_error 


libm 
libm87 


* 


fp_status 


lib 




fp_trap 


env 



1 11 rlev 

1UUCA 


ri<»f "in ititiii tiQinA 


T lhrarv 


* 


get_fp_control 


lib 

UDo / 


* 


get_fp_status 


lib 
lib87 


* 


getmem 


env 




hex_NaN 


libm 
libm87 




hex_NaNf 


libm 
libm87 


* 


infinity 


libc 


* 


init_fp 


lib 

lihS7 
11DO / 


* 


initdata 


env 




io_bufsiz 


env 




iob 


env 




lastbuf 


env 




lconv_data 


libc 




malloc_init 


libc 




memccpy 


libc 


* 


open_max 


env 




rand_seed 


libc 




readFile 


libc 




readStr 


libc 


* 


set_fp_control 


lib 
lib87 




sibuf 


env 
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Index 


Definition namp 


T .ihrarv 




smbuf 


env 




sobuf 


env 


* 


startup 


env 




_stdbuf 


env 




swrite 


libc 




top_of_func_stack 


libc 




wrtchk 


libc 




xflsbuf 


libc 


* 


_abs 


libc 




_abs_out_adrs 


env 


* 


_acos 


libm 
iiDmo / 


* 


_asin 


libm 
libm87 


* 


_atan 


libm 
libm87 


* 


_atan2 


libm 
libm87 


* 


_atexit 


libc 


* 


_atof 


libc 


* 


_atoi 


libc 


* 


_atol 


libc 


* 


_bsearch 


libc 



Index 


Definition name 


Library 


* 


_calloc 


libc 


* 


_ceil 


libm 
libm87 


* 


_clear_screen 


env 


* 


_clearerr 


libc 


* 


_close 


env 


* 


_cos 


libm 
libm87 


* 


_cosh 


libm 

llDIIlo / 




_count 


env 




_data_buff 


env 




_data_ptr 


env 


* 


_div 


libc 


* 


_errno 


libc 


* 


_exec_cmd 


env 


* 


_exit 


env 


* 


_exp 


libm 
libm87 


* 


_fabs 


libm 
libm87 


* 


_fclose 


libc 




_feof 


libc 


* 


_ferror 


libc 



152 



Chapter 7: Libraries 



Index 


Definition name 


Library 


* 


_fflush 


libc 


* 


_fgetc 


libc 


* 


_fgetpos 


libc 


* 


_fgets 


libc 


* 


_floor 


libm 
libm87 


* 


_fmod 


libm 

llDIIlo / 


* 


_fopen 


libc 


* 


_fprintf 


libc 


* 


_fputc 


libc 


* 


_fputs 


libc 


* 


_fread 


libc 


* 


_free 


libc 


* 


_frem 


libm 
libm87 


* 


_freopen 


libc 


* 


_frexp 


libm 
libm87 


* 


_fscanf 


libc 


* 


_fseek 


libc 


* 


_fsetpos 


libc 


* 


_ftell 


libc 



Index 


DpfStiitioti tifimp 


T .ihrarv 


* 


_fwrite 


libc 


* 


_getc 


libc 


* 


_getchar 


libc 


* 


_gets 


libc 


* 


_initsimio 


env 


* 


_isalnum 


libc 


* 


_isalpha 


libc 


* 


_iscntrl 


libc 


* 


_isdigit 


libc 


* 


_isgraph 


libc 


* 


_islower 


libc 


* 


_isprint 


libc 


* 


_ispunct 


libc 


* 


_isspace 


libc 


* 


_isupper 


libc 


* 


_isxdigit 


libc 


* 


_kill 


env 


* 


Jabs 


libc 


* 


_ldexp 


libm 
libm87 


* 


_ldiv 


libc 
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Index 


Definition name 


Library 


* 


_localeconv 


libc 


* 


Jog 


libm 
libm87 


* 


JoglO 


libm 

llDIIlo / 


* 


_longjmp 


libc 


* 


_lseek 


env 


* 


_malloc 


libc 


* 


_mblen 


libc 


* 


_mbstowcs 


libc 


* 


_mbtowc 


libc 


* 


_memchr 


libc 


* 


_memcmp 


libc 


* 


_memcpy 


libc 


* 


_memmove 


libc 


* 


_memset 


libc 


* 


_modf 


libm 
libm87 


* 


_open 


env 




_open_file 


env 


* 


_perror 


libc 


* 


_pos_cursor 


env 



Index 


Definition name 


Library 


* 


_pow 


libm 

llDIIlo / 


* 


_printf 


libc 


* 


_putc 


libc 


* 


_putchar 


libc 


* 


_puts 


libc 


* 


_qsort 


libc 


* 


_rand 


libc 


* 


_read 


env 


* 


_realloc 


libc 


* 


_remove 


libc 


* 


_rewind 


libc 


* 


_sbrk 


env 


* 


_scanf 


libc 


* 


_setbuf 


libc 


* 


_setj mp 


11 DC 


* 


_setlocale 


libc 


* 


_setvbuf 


libc 


* 


_sin 


libm 
libm87 


* 


_sinh 


libm 
libm87 
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Index 


Definition name 


Library 


* 


_sprintf 


libc 


* 


_sqrt 


libm 

llDIIlo / 


* 


_srand 


libc 


* 


_sscanf 


libc 


* 


_strcat 


libc 


* 


_strchr 


libc 


* 


_strcmp 


libc 


* 


_strcoll 


libc 


* 


_strcpy 


libc 


* 


_strcspn 


libc 


* 


_strerror 


libc 


* 


_strlen 


libc 


* 


_strncat 


libc 


* 


_strncmp 


libc 


* 


_strncpy 


libc 


* 


_strpbrk 


libc 


* 


_strrchr 


libc 


* 


_strspn 


libc 


* 


_strstr 


libc 


* 


_strtod 


libc 



Index 


Di'f "in itioii tifimp 


T ihrarv 


* 


_strtok 


libc 


* 


_strtol 


libc 


* 


_strtoul 


libc 


* 


_strxfrm 


libc 




_systemio_buf 


env 


* 


_tan 


libm 
libm87 


* 


_tanh 


libm 

llDIIlo / 


* 


_tolower 


libc 


* 


_toupper 


libc 


* 


_ungetc 


libc 


* 


_unlink 


env 


* 


_vfprintf 


libc 


* 


_vprintf 


libc 


* 


_vsprintf 


libc 




_wait_for_io 


env 


* 


_wcstombs 


libc 


* 


_wctomb 


libc 


* 


_write 


env 
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Support Library and Math Library Descriptions 

The remainder of this chapter describes the support and math library 
functions. Functions declared in the math.h include file are found in the math 
library archive file libm.a. All other functions are found in the support 
library archive file libc.a. 



Note The open, close, read, write, lseek, unlink, exit, _exit, _getmem, 

and sbrk functions have execution environment dependencies; therefore, these 
libraries are described in the "Environment-Dependent Routines" chapter. 
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abs, labs 

Return Integer Absolute Value 



Synopsis 



# include < stdlib.h> 

int abs (int i); 

long int labs (long int i); 



Description Abs returns the absolute value of its integer operand. 

Labs is similar to abs except that the argument and the returned value each 
have type long int. 



Warnings 



In two's-complement representation, the absolute value of the negative 
integer with the largest magnitude is undefined. This error is ignored. 



See Also 



floor. 
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assert 



Put Diagnostics into Programs 



Synopsis 



# include < assert.h> 

void assert (const char *expression); 



Description The assert macro puts diagnostics into programs. When it is executed, if 

expression is false (equal to zero), the assert macro writes information about 
the particular call that failed (including the text of the argument, the name of 
the source file, and the source line number - the latter are respectively the 

values of the preprocessing macros FILE_ and LINE ) on the standard 

error file in the format shown below. It then calls the _exit function. 

Assertion failed: <expression>, file < FILE >, line < LINE > 

Diagnostics When the assert.h header file is included and the macro NDEBUG is defined, 

the assert macro will be defined to do nothing. This allows you to compile 
your code with or without the assert checking by simply defining or undefining 
the macro NDEBUG. Assert returns no value. 



See Also 



_exit. 
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atexit 



Call Function at Program Termination 



Synopsis 



# include < stdlib.h> 

int atexit (void (*func)(void)); 



Description Atexit will register the func function to be called without arguments at normal 

program termination. Up to 32 separate function registrations can be 
performed. 



Diagnostics 
See Also 



Atexit returns zero if the registration succeeds, or non-zero if it fails. 



exit. 
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bsearch 

Binary Search a Sorted Table 

Synopsis # include < stdlib.h> 

void *bsearch ( 
const void *key, 
const void *base, 
size_t nel, size_t size, 
int (*compar)(const void *, const void *)); 

Bsearch is a binary search routine generalized from Knuth (6.2.1) Algorithm 
B. It returns a pointer into a table indicating where a datum maybe found. 
The table must be previously sorted in increasing order according to a 
provided comparison function. Key points to a datum instance to be sought in 
the table. Base points to the element at the base of the table. Nel is the 
number of elements in the table. Compar is the name of the comparison 
function, which is called with two arguments that point to the elements being 
compared. The function must return an integer less than, equal to, or greater 
than zero as accordingly the first argument is to be considered less than, equal 
to, or greater than the second. 

Notes The pointers to the key and the element at the base of the table should be of 

type pointer-to-element, and cast to type void pointer. The comparison 
function need not compare every byte, so arbitrary data maybe contained in 
the elements in addition to the values being compared. Although declared as 
void pointer type, the value returned should be cast into type 
pointer-to-element. 

Example The example below searches a table containing pointers to nodes consisting of 

a string and its length. The table is ordered alphabetically on the string in the 
node pointed to by each entry. 

This code fragment reads in strings and either finds the corresponding node 
and prints out the string and its length, or prints an error message. 
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#include <stdio.h> 
#include <stdlib.h> 

#define TABSIZE 1000 

struct node { /* these are stored in the table */ 

char ^string; 
int length; 

}; 

struct node table [TABSIZE] ; /* table to be searched */ 



struct node *node_ptr, node; 

int node_compare ( ) ; /* routine to compare 2 nodes */ 
char str_space [20] ; /* space to read string into */ 



node. string = str_space; 

while (scant ("%s", node. string) != EOF) { 

node_ptr = (struct node *) bsearch ( (void *) (&node) , 
(void *)table, TABSIZE, 
sizeof (struct node), node_compare) ; 
if (node_ptr != NULL) { 

(void) printf ( "string = %20s, length = %d\n", 
node_ptr->string, node_ptr->length) ; 

} else { 

(void) printf ( "not found: %s\n", node . string) , 



/* This routine compares two nodes based on an 

alphabetical ordering of the string field. */ 

int 

node_compare (nodel, node2) 
struct node *nodel, *node2; 
{ 

return strcmp (nodel->string, node2->string) ; 



See Also qsort. 

Diagnostics A NULL pointer is returned if the key cannot be found in the table. 

Bugs A random entry is returned if more than one entry matches the selection 

criteria. 
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div, Idiv 

Divide Functions 



Synopsis 



# include < stdlib.h> 

div_t div (int numer, int denom); 

ldiv_t Idiv (long int numer, long int denom); 



Description Div computes the quotient and remainder of the division of the numerator 

numerby the denominator denom. If the division is inexact, the sign of the 
quotient is that of the mathematical quotient, and the magnitude of the 
quotient is the largest integer less than the magnitude of the mathematical 
quotient. If the result cannot be represented, the behavior is undefined. 

Ldiv is similar to div except that the arguments and members of the returned 
structure (which has type ldiv_t) all have type long int. 

Diagnostics The div function returns a structure of type div_t, comprising both the 

quotient and the remainder. The structure is defined bystdlib.h as shown 
below. 



typedef struct 

} div_t; 
typedef struct { 



int quot; 
int rem; 



/* Quotient */ 
/* Remainder */ 



long int quot; /* Quotient */ 
long int rem; /* Remainder */ 
ldiv_t; 
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exp 



Exponential Functions 



Synopsis # include < math.h> 

double exp (double x); 

Description Exp returns e~ 



Diagnostics Exp sets errno to ERANGE and returns HUGE_VAL when the correct value 

would overflow, or 0 when the correct value would underflow. In addition to 
errno, bits in a global status flag or in the floating point coprocessor 
floating-point status register are set when error conditions arise. 

The error-handling is done by the run-time _fp_error routine. 



See Also 



_fp_error, _get_fp_status, "Behavior of Math Library Functions" chapter. 
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fclose, fflush 

Close or Flush a Stream 



Synopsis 



# include < stdio.h> 

int fclose (FILE *stream); 

int fflush (FILE *stream); 



Description Fclose causes any buffered data for the named stream to be written out, and 

the stream to be closed. Buffers allocated by the standard input/output system 
are freed. 

Fclose is performed automatically for all open files upon calling exit. 

Fflush causes any buffered data for the named stream to be written to that file. 
If the argument is NULL, then all open files are flushed. The stream or 
streams remain open. 

Diagnostics These functions return 0 for success, and EOF if any error (such as trying to 

write to a file that has not been opened for writing) was detected. 



See Also 



close, exit, fopen, setbuf. 
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Synopsis 



Description 



Note 



See Also 



ferror, feof, clearerr 

Stream Status Inquiries 

# include < stdio.h> 
int ferror (FILE *stream); 
int feof (FILE *stream); 
void clearerr (FILE *stream); 



ferror returns non-zero when an I/O error has previously occurred reading 
from or writing to the named stream, otherwise zero. Unless cleared by 
clearerr, or unless the specific stdio routine so indicates, the error indication 
lasts until the stream is closed. 

Feo/returns non-zero when EOF has previously been detected reading the 
named input stream, otherwise zero. 

Clearerr resets the error indicator and EOF indicator to zero on the named 
stream. 



These functions are implemented as macros and functions. To use a function 
instead of a macro, # undef the macro before function invocation. 



open, fopen. 
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fgetpos, fseek, fsetpos, rewind, ftell 

Position File Pointer 

Synopsis # include < stdio.h> 

int fgetpos (FILE *stream, fpos_t *pos); 

int fseek (FILE *stream, long offset, int ptrname); 

int fsetpos (FILE *stream, const fpos_t *pos); 

long ftell (FILE *stream); 

void rewind (FILE *stream); 

Description Fgetpos stores the current value of the file pointer on the stream in the object 

pointed to hypos. The value stored contains unspecified information usable 
by the fsetpos function for repositioning the stream to its position at the time 
of the call to the fgetpos function. 

Fsetpos sets the file pointer for the stream to the value of the object pointed to 
by pos which is a value returned by an earlier call to fgetpos on the same stream. 

Fseek sets the position of the next input or output operation on the stream. 
The new position is at the signed distance offset bytes from the beginning, from 
the current position, or from the end of the file, according as ptrname has the 
value SEEK_SET, SEEK_CUR, or SEEK_END. 

Rewind ( stream ) is equivalent to (void) fseek ( stream , OL, SEEK_SET). 

Fsetpos, fseek, and rewind clear the end-of-file indicator and undo any effects of 
the ungetc function on the same stream. After an fsetpos, fseek, or rewind call, 
the next operation on an update stream maybe either input or output. Rewind 
also does an implicit clearerr call. 

Ftell returns the offset of the current byte relative to the beginning of the file 
associated with the named stream. 
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See Also 
Diagnostics 



Warning 



lseek, fopen, ungetc. 



The fgetpos and fsetpos functions return zero if successful; otherwise, they 
return non-zero and errno is set to a non-zero value. 

Fseek returns non-zero for improper seeks, otherwise zero. An improper seek 
can be, for example, an fseek done on a file that has not been opened via fopen; 
in particular,/ieefc may not be used on a terminal. 

Ftell returns -1 for error conditions and sets errno to a non-zero value. If 
either the argument to ftell is NULL or if the file is not open, then ftell sets 
errno to EBADF. 



In UNIX-base operating sytems, the offset returned by ftell is measured in 
bytes, and a program may seek to positions relative to that offset. Portability 
to non-UNIX systems requires that an offset be used by fseek directly. Do not 
use the offset in calculations — the offset might not be measured in bytes. 
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Synopsis 



Description 



See Also 



floor, ceil, fmod, frem, fabs 

Floor, Ceiling, Remainder, and Absolute Value 

# include < math.h> 

double floor (double x); 
double ceil (double x); 
double fmod (double x, double y); 
double frem (double x, double y); 
double fabs (double x); 

F/oorreturns the largest integer (as a double -precision number) not greater 
than x. 

Ceil returns the smallest integer (as a double -precision number) not less than x. 

Fmod returns the floating-point remainder of the division of xbyy. NaN if y is 
zero or + /-HUGE_VAL if x/y would overflow; otherwise the number/with the 
same sign as x, such that x = iy + /for some integer and 1/1 < I y\ . 

Frem is the same as fmod except that the remainder is computed in 
round-to-nearest mode, and the result may have a different sign than x. For 
example: 

fmod (x, y) = x - (y*i) Where i = (int) (x/y) 

frem (x, y) = x - (y*i) Where i = (int) (x/y + 0.5) 

fmod (5.2, 10) = 5.2 - (10*0) = 5.2 
frem (5.2, 10) = 5.2 - (10*1) = -4.8 

Fabs returns the absolute value of x, I x\ ; errno is set whenever an exception 
condition occurs. 



abs, "Behavior of Math Library Functions" chapter. 
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fopen, freopen 



Open or Re-Open a Stream File 



Synopsis 



# include < stdio.h> 

FILE *fopen ( 

const char *file_name, 

const char *type); 

FILE *freopen ( 
const char *file_name, 
const char *type, 
FILE*stream); 



Description Fopen opens the file named by file_name and associates a stream with it. 

Fopen returns a pointer to the FILE structure associated with the stream. 

File_name points to a character string that contains the name of the file to be 
opened. 

Type is a character string having one of the following values: 



"w", "wb" 
"a", "ab" 



Open for reading. 

Truncate or create for writing. 

Append; open for writing at end of file, or create for 
writing. 



"r+ ", "rb+ ", "r+ b" Open for update (reading and writing). 
"w+ ", "wb+ ", "w+ b" Truncate or create for update. 

"a+ ", "ab+ ", "a+ b" Append; open or create for update at end-of-file. 

A character "b" in the type string signifies that the file is a binary file. In this 
implementation, the presence or absence of the "b" has no effect. 
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Freopen substitutes the named file in place of the open stream. The original 
stream is closed, regardless of whether the open ultimately succeeds. Freopen 
returns a pointer to the FILE structure associated with stream. 

Freopen is typically used to attach the preopened streams associated with stdin, 
stdout, and stderr to other files. 

When a file is opened for update (i.e., the character "+ " is present in the type 
string), both input and output maybe done on the resulting stream. However, 
input may not be directly followed by output unless there is an intervening call 
to fflush or to one of the file positioning functions (rewind, f seek, fsetpos). The 
same is true for following output directly with input. 

When a file is opened for append (i.e., the character "a" is present in the type 
string), information already present in the file cannot be overwritten. Fseek 
maybe used to reposition the file pointer to any position in the file, but when 
output is written to the file, the current file pointer is disregarded. Undefined 
behavior will occur if the file is also opened for update and the preceding rules 
for update mode are not followed. 

See Also open, fclose, fseek. 

Diagnostics Fopen and freopen return a NULL pointer if file-name cannot be accessed, if 

there are too many open files, or if the arguments are incorrect. 
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_fp_error 

Floating-Point Error Functions 

Synopsis # include < fp_control.h> 

void _clear_fp_status (void); 
int _get_fp_status (void); 
void _set_fp_control (int mode); 
int _get_fp_control (void); 
void _init_fp (void); 

Description Technically, _fp_error is a run-time routine in that it is only called from other 

run-time library and math library functions. Its purpose is to simulate the 
exception processing that is present on the 8087 NPX. Therefore, _Jp_error is 
referenced only when the 8086/186 library libm.a) is loaded. 

_Jp_error composes the return value defined by the IEEE Floating Point 
Standard 754 (see the "Behavior of Math Library Functions" chapter) and 
returns the value if trapping does not take place. The trapping decision is 
handled by a piece of common code in the run-time library. This code inspects 
a global control flag to see if the trap bit associated with the current exception 
is set. If the bit is set, an error message is composed and control passes to the 
monitor program so that the message can be displayed. If the bit is not set, 
then a global status flag is updated to reflect the exception that just occurred 
and processing continues. 

The following functions can be used to inspect and set the global control flag 
and the global status flag: 

_clear Jp_status clears the global status flag. 

-get _jp_status returns the global status flag. 

_set _Jp_control sets the global control flag to mode. 
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_get _Jp_control returns the global control flag. 

Jnitjp resets the 8087 by executing the FINIT instruction (if lib87.a is being 
used) and clears the global status flag and the global control flag. 

The 8086/186 libraries always perform operations in double precision and 
round to nearest. By default, trapping is enabled on all floating-point 
exceptions except inexact results. The following macro disables trapping: 

NOTRAP Disable all traps. 

The remaining macros maybe OR'ed together to form mode when invoking 
_set Jp_control. (Do not OR them with NOTRAP.) 



INEXACT Trap on inexact result. 

DIVZERO Trap on division by zero. 

UNDERFLOW Trap on underflow. 

OVERFLOW Trap on overflow. 

OPERROR Trap on operand error. 



PLOSS Trap on loss of precision (applies to 8086/186 — not 

8087— math libraries). 

The following macros maybe used when inspecting the return value from 
_get _Jp_status: 

NOERRORS No errors have been detected since the last invocation 

of _dear Jp_status. 

INEXACT 

DIVZERO 

UNDERFLOW 

OVERFLOW 

OPERROR 

PLOSS 
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When using the 8087 chip, the control word contains some additional 
information. The 8087 allows you to control trapping, precision, infinity, and 
rounding behaviors. 

The following macros can be used to select the 8087 behavior that is desired: 
Precision: 



SGLPREC 

DBLPREC 

EXTPREC 
Infinity: 

PROJECTIVE 

AFFINE 
Rounding: 

RNDNEAR 

RNDNEGINF 

RNDPOSINF 

RNDZERO 
Trapping: 

DENORM_OP 



Single precision (32-bit floatingpoint number). 
Double precision (64-bit floatingpoint number). 
Extended precision (80-bit floatingpoint number). 

Infinity is unsigned. 

Distinguish + infinity from -infinity. 

Round towards the "nearest" number. 
Round towards negative infinity. 
Round towards positive infinity. 
Round towards zero. 

Trap when a denormalized operand is encountered. 



Select exactly one macro each from the precision, rounding, and infinity 
categories every time that _set _Jp_control is called. Any number of trapping 
macros can be selected. 

Note that an OPERROR trap can occur when a 8087 floatingpoint register is 
used before it is initialized. 



Example 



You may change the control word without respecifying all of the different 
categories. This can be done by using the current value of the control variable 
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and using masking. For example, the following function call turns on 
divide-by-zero trapping without altering any of the other control flags: 

_set_fp_control (_get_fp_control ( ) | DIVZERO ) ; 

The next example turns off the overflow and underflow traps: 

_set_fp_control (_get_f p_control () & 
~ (UNDERFLOW | OVERFLOW ) ) ; 
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fread, fwrite 

Buffered Binary I/O to Stream 



Synopsis 



# include < stdio.h> 

size_t fread (void *ptr, size_t size, 

size_t nitems, FILE *stream); 

size_t fwrite (const void *ptr, size_t size, 
size_t nitems, FILE *stream); 



Description Fread copies, into an array pointed to by ptr, nitems items of data from the 

named input stream, where an item of data is a sequence of bytes (not 
necessarily terminated by a null byte) of length size. Fread stops appending 
bytes if an end-of-file or error condition is encountered while reading stream, 
or if nitems items have been read. Fread leaves the file pointer in stream, if 
defined, pointing to the byte following the last byte read if there is one. Fread 
does not change the contents of stream. 

Fwrite appends at most nitems items of data from the array pointed to by ptr to 
the named output stream. Fwrite stops appending when it has appended 
nitems items of data or if an error condition is encountered on stream. Fwrite 
does not change the contents of the array pointed to by ptr. 

The argument size is typically sizeof( *ptr) where the pseudo-function sizeof 
specifies the length of an item pointed to by ptr. If ptr points to a data type 
other than void it should be cast into a pointer to void. 



See Also read, write, fopen, getc, gets, printf, putc, puts, scanf. 

Diagnostics Fread and fwrite return the number of items read or written. If size or nitems is 

zero, no characters are read or written and 0 is returned by both fread and 
fwrite. 
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Synopsis 



Description 



Diagnostics 



See Also 



frexp, Idexp, modf 

Return Mantissa and Exponent 

# include < math.h> 
double frexp (double value, int *eptr); 
double Idexp (double value, int *exp); 
double modf (double value, double *iptr); 



Every non-zero number can be written uniquely as x * 2n where the "mantissa" 
(fraction) x is in the range 0.5 < = I x\ < 1.0, and the "exponent" n is an integer. 

Frexp returns the mantissa of a double value, and stores the exponent 
indirectly in the location pointed to by eptr. If value is zero, both results 
returned by frexp are zero. 

Ldexp returns the quantity value * 2exp. 

Moii/returns the signed fractional part of value and stores the integral part 
indirectly in the location pointed to by iptr. 



If ldexp would cause overflow, + /-HUGE_VAL is returned (according to the 
sign of value), and errno is set to ERANGE. If ldexp would cause underflow, 
zero is returned and errno is set to ERANGE. 



fp_error, "Behavior of Math Library Functions" chapter. 
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Synopsis 
Description 



See Also 

Diagnostics 

Warning 

Bugs 



getc, getchar, fgetc 

Get Character from Stream 

# include < stdio.h> 

int getc (FILE *stream); 

int getchar (void) ; 

int fgetc (FILE *stream); 



Getc returns the next character (i.e., byte) from the named input stream, as an 
integer. It also moves the file pointer, if defined, ahead one character in 
stream. Getchar is defined as getc(stdin). Getc is a macro and so cannot be 
used if a function is necessary; for example one cannot have a function pointer 
point to it. Getchar is implemented as a macro and as a function. To use a 
function instead of a macro, # undef the macro before function invocation. 

Fgetc behaves like getc, but is a function rather than a macro. Fgetc runs more 
slowly than getc, but it takes less space per invocation and its name can be 
passed as an argument to a function. 



fclose, ferror, fopen, fread, gets, putc, scanf. 



These functions return the constant EOF at end-of-file or upon an error. 



If the integer value returned by getc, getchar, or fgetc is stored into a character 
variable and then compared against the integer constant EOF, the comparison 
may never succeed, because sign-extension of a character on widening to 
integer is machine-dependent. 



Because it is implemented as a macro, getc treats incorrectly a stream 
argument with side effects. In particular, getc(*f+ + ) does not work sensibly. 
Fgetc should be used instead. 
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gets, fgets 

Get a String from a Stream 



Synopsis 



# include < stdio.h> 
char *gets (char *s); 

char *fgets (char *s, int n, FILE *stream); 



Description Gets reads characters from the standard input stream, stdin, into the array 

pointed to by s, until a new-line character is read or an end-of-file condition is 
encountered. The new-line character is discarded and the string is terminated 
with a null character. 

Fgets reads characters from the stream into the array pointed to by s, until n-\ 
characters are read, or a new-line character is read and transferred to s, or an 
end-of-file condition is encountered. The string is then terminated with a null 
character. 



See Also 
Diagnostics 



ferror, fopen, fread, getc, puts, scanf. 



If end-of-file is encountered and no characters have been read, no characters 
are transferred to s and a NULL pointer is returned. If a read error occurs, 
such as trying to use these functions on a file that has not been opened for 
reading, a NULL pointer is returned, and the contents of s are indeterminate. 
Otherwise s is returned. 
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isalpha, isupper, islower, ... 

Classify Characters 

Synopsis # include < ctype.h> 

int isalpha (int c); 

Description These routines classify character-coded integer values by table lookup. Each is 

a predicate returning nonzero for true, zero for false. These routines are 
implemented both as macros and functions. To use a function instead of a 
macro, # undef the macro before function invocation. 



isalpha c is a letter. 

isupper c is an upper-case letter. 

islower c is a lower-case letter. 

isdigit c is a digit [0-9]. 

isxdigit c is a hexadecimal digit [0-9], [A-F] or [a-f]. 

isalnum c is an alphanumeric (letter or digit). 

isspace c is a space, tab, carriage return, new-line, vertical tab, 

or form-feed. 

ispunct c is a printing character that is neither a control 

character nor an alphanumeric character nor a space. 

isprint c is a printing character, code 040 (space) through 0176 

(tilde). 

isgraph c is a printing character, like isprint except false for 

space. 
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iscntrl c is a delete character (0177) or an ordinary control 

character (less than 040). 

Diagnostics If the argument to any of these macros is not in the domain of the function, 

the result is undefined. The domain for these functions is the integer values 
[ 0, 255 ] and EOF. 
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localeconv 

Locale Conversion 

Synopsis # include < locale.h> 

struct lconv *localeconv (void); 

Description localeconv sets the components of an object of type struct lconv to the 

appropriate numeric quantity formatting values for the current locale. 

Within the structure lconv, members of type char * point to strings. Any char 
pointer, except char *decimal_point may point to a null string ("") to indicate 
that the value is either not available in the current locale or of zero length in 
the current locale. 

The following are members of the lconv structure: 
char *decimal_point 

is the decimal point character used to format 
non-monetary quantities. 

char *thousands_sep 

is used to separate groups of digits before the decimal 
point in non-monetary quantities. 

char *grouping 

is a string, the elements of which indicate the size of 
each group of digits in formatted non-monetary 
quantities. 

char *int_curr_symbol 

is the international currency symbol used in the current 
locale. The first three characters in this string contain 
the alphabetic international currency symbol in 
accordance with ISO 4217 Codes for the Representation 
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of Currency and Funds. The fourth character is (last 
before the null terminator) is the character used to 
separate the currency symbol from the monetary 
quantity. 

char *currency_symbol 

is the local currency symbol for the current locale, 
char *mon_decimal_point 

is the decimal point used to format the monetary values, 
char *mon_thousands_sep 

is the separator for groups of digits before the decimal 
point in the monetary values. 

char *mon_grouping 

is a string, the elements of which indicate the size of 
each group of digits in formatted monetary quantities. 

char *positive_sign 

is the string used to signify non-negative formatted 
monetary values. 

char *positive_sign 

is the string used to signify negative formatted monetary 
values. 

char int_frac_digits 

is the number of fractional digits (after the decimal 
point) to display in an internationally formatted 
monetary value. 

char frac_digits 

is the number of fractional digits (after the decimal 
point) to display in a formatted monetary value. 
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char p_cs_precedes 

for a formatted non-negative monetary value, is set to 
one if the currency_symbol precedes the value or set to 
zero if the currency_symbol follows the value. 

char p_sep_by_space 

for a formatted non-negative monetary value, is set to 
one if the currency_symbol is separated from the value 
by a space and set to zero if it is not separated from the 
value by a space. 

char n_cs_precedes 

for a formatted negative monetary value, is set to one if 
the currency_symbol precedes the value or set to zero if 
the currency_symbol follows the value. 

char p_sep_by_space 

for a formatted negative monetary value, is set to one if 
the currency_symbol is separated from the value by a 
space and set to zero if it is not separated from the 
value by a space. 

char p_sign_posn 

is a value indicating the positioning of the negative sign 
for a formatted non-negative monetary value. 

char n_sign_posn 

is a value indicating the positioning of the negative sign 
for a formatted negative monetary value. 

The elements grouping and mon_grouping specify the grouping of digits in 
non-monetary and monetary quantities. Both strings are strings of grouping 
counts. The first element of the string, say s[0], unless it is CHAR_MAX, is 
the number of digits to group before the first separator character. s[l], unless 
it is zero or CH AR_MAX, is the number of digits to group after grouping s[0] 
digits. s[2], unless it is zero or CHAR_MAX, is the number of digits to group 
after s[0] digits and s[l] digits have been grouped. And so on. If s[i] is zero, 
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then the value in s[i-l] is the grouping value for all subsequent digits. If s[i] is 
CH AR_MAX, then no further grouping is performed. 

The value of either p_sign _posn and n_sign _posn is interpreted in the following 
way: 



0 Parentheses surround the quantity and currency _symbol. 

1 The sign string precedes the quantity and 

currency _sym bol. 

2 The sign string follows the quantity and currency <_symbol. 

3 The sign string immediately precedes the 
currency _sym bol. 

4 The sign string immediately follows the currency _symbol. 



Diagnostics The localeconv routine returns a pointer to the filled object. The returned 

structure is not to be modified directly by the program, but maybe overwritten 
by further calls to localeconv. In addition, calls to setlocale with the categories 
LC_ALL, LC_MONETARY, and LC_NUMERIC may overwrite the contents 
of the structure. 

Note The locale supported by the libraries is the "C" locale, localeconv will return 

the "C" locale only. The following table lists the return values for the various 
structure elements. 



184 



Chapter 7: Libraries 

localeconv 



Additionally, there is a macro MB_CUR_MAX defined in stdlib.h that returns 
the maximum number of bytes a multi-byte character could have in the current 
locale. Because multi-byte characters are not supported, this macro always 
returns one. 

See Also setlocale 



Table 7-2. Element Values Returned by localeconv 



Element 


Returned Value 


char *decimal_point 


IT IT 


char *thousands_sep 




char *grouping 




char *int_curr_symbol 




char *currency_symbol 




char *mon_decimal_point 




char *mon_thousands_sep 




char *mon_grouping 




char *positive_sign 




char *negative_sign 




char int_frac_digits 




char frac_digits 


CHARJVIAX 


char p_cs_precedes 


CHAR_MAX 


char p_sep_by_space 


CHAR_MAX 


char n_cs_precedes 


CHAR_MAX 


char n_sep_by_space 


CHAR_MAX 


char p_sign_posn 


CHAR_MAX 


char n_sign_posn 


CHAR_MAX 
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log, Iog10 



Logarithm Functions 



Synopsis 



# include < math.h> 
double log (double x); 
double loglO (double x); 



Description Log returns the natural logarithm ofx. The value of x must be positive. 

LoglO returns the logarithm base ten of x. The value of x must be positive. 

Diagnostics Log and loglO return -HUGE_VAL and set errno to EDOM when x is negative. 

Log and loglO return an NaN and set errno to ERANGE when x is zero. The 
error action is determined by the bits of the global control flag. 

These error-handling procedures maybe changed with the function _fp_error. 



See Also 



_fp_error, "Behavior of Math Library Functions" chapter. 
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malloc, free, realloc, calloc 

Main Memory Allocator 

Synopsis # include < stdlib.h> 

void *malloc (size_t size); 

void free (void *ptr); 

void *realloc (void *ptr, size_t size); 

void *calloc (size_t nelem, size_t elsize); 

Description Malloc and free provide a simple general-purpose memory allocation package. 

Malloc returns a pointer to a block of at least size bytes suitably aligned for any 
use. 

The argument to free is a pointer to a block previously allocated by malloc; 
after free is performed this space is made available for further allocation. 

Undefined results will occur if the space assigned by malloc is overrun or if 
some random number is handed to free. 

Malloc calls _getmem to get more memory when there is no suitable space 
already free. 

Realloc changes the size of the block pointed to by ptr to size bytes and returns 
a pointer to the (possibly moved) block. The contents will be unchanged up to 
the lesser of the new and old sizes. If the size argument to realloc is zero, then 
a free operation is done. 

If no free block of size bytes is available in the storage arena, then realloc will 
ask malloc to enlarge the arena by size bytes and will then move the data to the 
new space. 

Calloc allocates space for an array of nelem elements of size elsize. The space 
is initialized to zeros. 

Each of the allocation routines returns a pointer to space suitably aligned 
(after possible pointer coercion) for storage of any type of object. 
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See Also _getmem. (Described in the "Environment-Dependent Routines" chapter.) 

Diagnostics Malloc, realloc and calloc return a NULL pointer if there is no available 

memory or if the arena has been detectably corrupted by storing outside the 
bounds of a block. When this happens the block pointed to by ptr may be 
destroyed. 
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mblen, mbstowcs, mbtowc, wcstombs, wctomb, 
strxfrm 

Multi-byte Character Operations 

Synopsis # include < stdlib.h> 

int mblen (const char *s, size_t n) ; 
size_t mbstowcs (wchar_t *pwcs, const char *s, size_t n); 
int mbtowc (wchar_t *pwc, const char *s, size_t n); 
size_t wcstombs (char *s, const wchar_t *pwcs, size_t n); 
int wctomb (char *s, wchar_t wchar); 

# include < string.h> 

size_t strxfrm (char *sl, const char *s2, size_t n); 

Description mblen, because multi-byte characters are not supported, returns zero if the 

first argument is NULL — without regard to the value of n. If the first 
argument is not NULL, then mblen returns negative one if n is zero or returns 
one if n is nonzero. 

mbstowcs copies n multi-byte characters from the second argument into the 
first, transforming each multi-byte character into its wide character 
representation. Because multi-byte characters are not supported, mbtowcs 
copies n bytes from the second argument to the first while transforming each 
byte to its wide character representation. Transformation is accomplished by 
moving the character value into the least significant byte and zero-filling the 
remaining bytes of the wide character. If there is room left in the first 
argument after copying all bytes, mbstowcs appends a null terminating 
character to the first argument, mbstowcs returns the number of multi-bytes 
copied (which, in this implementation, is the number of bytes copied). That 
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number maybe less than n if a null character is found in the second argument 
before n bytes are read. 

mbtowc transforms the multi-byte character from the second argument into its 
wide character representation and places it into the first argument, mbtowc 
uses at most n bytes from the second argument. Because multi-byte characters 
are not supported, mbtowc copies n characters from the second argument into 
the first and transforms each character as it is copied by moving the character 
value into the least significant byte and zero-filling the remaining bytes of the 
wide character, mbtowc returns zero if the second argument is NULL or 
returns one if the second argument is not NULL. 

wcstombs copies n wide characters from the second argument into the first 
while transforming each wide character into its multi-byte character 
representation. Because multi-byte characters are not supported, wctombs 
copies at most n characters from the second argument into the first while 
transforming each character by copying just the least significant byte of the 
wide character. If there is room in the first argument after copying, wcstombs 
appends a null terminator, wcstombs returns the number of bytes copied, 
which maybe less than n if a null terminating character is found in the second 
string before n bytes are read. 

wctomb transforms the wide character pointed to by the second argument into 
a multi-byte character and places it in the first argument. The wide character 
will be represented by at most MB_CUR_MAX characters in the multi-byte 
character. Because multi-byte characters are not supported, MB_CUR_MAX 
is always one and therefore the wide character transformed into a single 
character. The transformation is accomplished by copying the least significant 
byte of the wide character into the char, wctomb returns zero if the second 
argument is NULL or returns one if the second argument is not NULL. 

strxfrm, because multi-byte characters are not supported, simply does a 
byte-by-byte copy from s2 to si of up to n characters. 

Note In addition to the multi-byte character operations, the macro MB_CUR_MAX 

returns the maximum number of bytes a multi-byte character could have in the 
current locale. Because multi-byte characters are not supported, this macro 
always returns one. 
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memchr, memcmp, memcpy, memmove, memset 



Memory Operations 



Synopsis 



# include < string.h> 



void *memchr (const void *s, int c, size_t n); 
int memcmp (const void *sl, const void *s2, size_t n); 
void *memcpy (void *sl, const void *s2, size_t n); 
void *memmove (void *sl, const void *s2, size_t n); 
void *memset (void *s, int c, size_t n); 



Description These functions operate efficiently on memory areas (arrays of characters 

bounded by a count, not terminated by a null character). They do not check 
for the overflow of any receiving memory area. 

Memchr returns a pointer to the first occurrence of character c in the first n 
characters of memory area s, or a NULL pointer if c does not occur. 

Memcmp compares its arguments, looking at the first n characters only, and 
returns an integer less than, equal to, or greater than 0, according as si is 
lexicographically less than, equal to, or greater than s2. (n equal to zero yields 
equality.) In some operating systems, memcmp uses unsigned char for 
character comparisons. This may not be true for other implementations. 

Memcpy copies n characters from memory area s2 to si. It returns si. 

Memmove works like memcpy except that memmove handles overlapping 
moves properly. 

Memset sets the first n characters in memory area s to the value of character c. 
It returns s. 



Bugs 
See Also 



Strcpy and memcpy may fail for overlapping moves; use memmove instead. 



strchr, strrchr, strcmp, strncmp, strcpy, strncpy. 
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perror, errno 



System Error Messages 



Synopsis 



# include < stdio.h> 

void perror (const char *s); 

# include < errno.h> 
extern int errno; 



Description Perror produces a message on the standard error output, describing the last 

error encountered during a call to a system or library function. The argument 
string 5 is printed first, then a colon and a blank, then the message and a 
new-line. To be of most use, the argument string should include the name of 
the program that incurred the error. The error number is taken from the 
external variable errno, which is set when errors occur but not cleared when 
non-erroneous calls are made. 

The value of errno might not be what you expect if your program uses 
multitasking; errno can be overwritten by some library routines. 



See Also 



strerror. 
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pow 

Power Function 



Synopsis 



# include < math.h> 

double pow (double x, double y); 



Description Pow returns x? '. If x is zero, y must be positive. If x is negative, y must be an 

integer. 

Diagnostics Pow returns NaN (Not a Number) and sets errno to EDOM when x is 0 and y is 

non-positive, or when x is negative and y is not an integer. The error action is 
determined by the bits of the global control flag. When the correct value for 
pow would overflow or underflow, pow returns + /-HUGE_VAL or 0 
respectively, and sets errno to ERANGE. 

These error-handling procedures maybe changed with the function _fp_error. 



See Also 



_fp_error, "Behavior of Math Library Functions" chapter. 
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printf, fprintf, sprintf 

Print Formatted Output 

Synopsis # include < stdio.h> 

int printf (const char *format, ...); 

int fprintf (FILE *stream, const char *format, ...); 

int sprintf (char *s, const char *format, ...); 

Description Printf places output on the standard output stream stdout. Fprintf places 

output on the named output stream. Sprintf places "output", followed by the 
null character (\0), in consecutive bytes starting at s; it is the user's 
responsibility to ensure that enough storage is available. Each function 
returns the number of characters transmitted (not including the \0 in the case 
of sprintf), or a negative value if an output error was encountered. 

Each of these functions converts, formats, and prints its args under control of 
the format. The format is a character string that contains two types of objects: 
plain characters, which are simply copied to the output stream, and conversion 
specifications, each of which results in fetching of zero or more args. The 
results are undefined if there are insufficient args for the format. If the format 
is exhausted while args remain, the excess args are evaluated but ignored. 

The behavior of the sprintf function is undefined if the destination array is also 
one of the other arguments. This undefined behavior of sprintf is particularly 
important because the behavior has changed between versions of the HP cross 
compilers. 

Each conversion specification is introduced by the character %. After the % 
the following appear in sequence: 

Zero or more flags, which modify the meaning of the conversion 
specification. 

An optional decimal digit string specifying a minimum 'field width". If the 
converted value has fewer characters than the field width, it will be padded 
on the left (or right, if the left-adjustment flag described below, has 
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been given) to the field width. If the field width for a conversion is 
preceded by a 0, the padding is done with zeros instead of spaces. 

A precision that gives the minimum number of digits to appear for the d, i, 
o, u, x, or X conversions, the number of digits to appear after the decimal 
point for the e, E, and f conversions, the maximum number of significant 
digits for the g and G conversions, or the maximum number of characters 
to be printed from a string in s conversion. The precision takes the form 
of a period (.) followed by a decimal digit string; a null digit string is 
treated as zero. 

An optional 1 (ell) specifying that a following d, i, o, u, x, or X conversion 
character applies to a long integer arg, or an optional h specifying that a 
following d, i, o, u, x, or X conversion character applies to a short integer 
arg. A "%ln" format means that the argument is a pointer to a long integer 
and a "%hn" format means that the argument is a pointer to a short 
integer. 

An optional L specifies that a following e, E, f, g, or G conversion 
character applies to a long double arg. 

An 1 or L before any other conversion character is ignored. 

A character that indicates the type of conversion to be applied. 

A field width or precision maybe indicated by an asterisk (*) instead of a digit 
string. In this case, an integer arg supplies the field width or precision. The 
arg that is actually converted is not fetched until the conversion letter is seen, 
so the args specifying field width or precision must appear before the arg (if 
any) to be converted. 
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The flag characters and their meanings are: 

- The result of the conversion will be left -justified within 

the field. 

+ The result of a signed conversion will always begin with 

a sign (+ or -). 

blank If the first character of a signed conversion is not a sign, 

a blank will be prefixed to the result. This implies that 
if the blank and + flags both appear, the blank flag will 
be ignored. 



# This flag specifies that the value is to be converted to an 

"alternate form." For c, d, i, s, and u conversions, the 
flag has no effect. For o conversion, it increases the 
precision to force the first digit of the result to be a 
zero. For x or X conversion, a non-zero result will have 
Ox or OX prefixed to it. For e, E, f, g, and G conversions, 
the result will always contain a decimal point, even if no 
digits follow the point (normally, a decimal point 
appears in the result of these conversions only if a digit 
follows it). For g and G conversions, trailing zeroes will 
not be removed from the result (which they normally 
are). 

The conversion characters and their meanings are: 



d,i,o,u,x,X The integer arg is converted to signed decimal (d or i), 

unsigned octal, unsigned decimal, or hexadecimal 
notation (x and X), respectively; the letters abcdef are 
used for x conversion and the letters ABCDEF for X 
conversion. The precision specifies the minimum 
number of digits to appear; if the value being converted 
can be represented in fewer digits, it will be expanded 
with leading zeroes. (For compatibility with older 
versions, padding with leading zeroes may alternatively 
be specified by prefixing a zero to the field width. This 
does not imply an octal value for the field width.) The 
default precision is 1. The result of converting a zero 
value with a precision of zero is a null string. 
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f The double arg is converted to decimal notation in the 

style "[-]ddd.ddd", where the number of digits after the 
decimal point is equal to the precision specification. If 
the precision is missing, six digits are output; if the 
precision is explicitly 0, no decimal point appears. 

e, E The double arg is converted in the style 

"[-]d.ddde+ /-ddd", where there is one digit before the 
decimal point and the number of digits after it is equal 
to the precision; when the precision is missing, six digits 
are produced; if the precision is zero, no decimal point 
appears. The E format code will produce a number 
with E instead of e introducing the exponent. The 
exponent always contains at least two digits. 

g, G The double arg is printed in style f or e (or in style E in 

the case of a G format code), with the precision 
specifying the number of significant digits. The style 
used depends on the value converted: style e will be 
used only if the exponent resulting from the conversion 
is less than -4 or greater than the precision. Trailing 
zeroes are removed from the result; a decimal point 
appears only if it is followed by a digit. 

c The character arg is printed. 

s The arg is taken to be a string (character pointer) and 

characters from the string are printed until a null 
character (\0) is encountered or the number of 
characters indicated by the precision specification is 
reached. If the precision is missing, it is taken to be 
infinite, so all characters up to the first null character 
are printed. A NULL value for arg will yield undefined 
results. 

p The arg is taken to be a pointer to void. The value of 

the pointer is converted to a sequence of printable 
characters, in the same manner as %x. 
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n The arg is taken to be a pointer to an integer into which 

is written the number of characters written to the 
output stream so far by this call to printf. No argument 
is converted. 

% Print a %; no argument is converted. 

In no case does a non-existent or small field width cause truncation of a field; 
if the result of a conversion is wider than the field width, the field is simply 
expanded to contain the conversion result. Characters generated by printf and 
fprintf are printed as if putc had been called. 

Examples To print a date and time in the form "Sunday, July 3, 10:02", where weekday 

and month are pointers to null-terminated strings: 

printf ("%s, %s %d, %d:%.2d", weekday, month, day, hour, 
min) ; 

To print pi to 5 decimal places: 

printf ("pi = %.5f", 4 * atan(l.O)); 

The value of stringl is undefined after the following line of code: 

sprintf (stringl, "%s %d", stringl, integerl); 



See Also putc, scanf, vprintf. 
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putc, putchar, fputc 

Put a Character on a Stream 

Synopsis # include < stdio.h> 

int putc (int c, FILE *stream); 

int putchar (int c); 

int fputc (int c, FILE *stream); 

Description Putc writes the character c onto the output stream (at the position where the 

file pointer, if defined, is pointing). Putchary c ) is defined as putc ( c, stdout ). 
Putc is implemented as a macro; putchar is implemented as a macro and as a 
function. To use a function instead of a macro, # undef the macro before 
function invocation. 

Fputc behaves like putc, but is a genuine function rather than a macro; it may 
therefore be used as an argument. Fputc runs more slowly than putc, but it 
takes less space per invocation and its name can be passed as an argument to a 
function. 

Output streams, with the exception of the standard error stream stderr, are by 
default buffered if the output refers to a file. The standard error output 
stream stderr is by default unbuffered, but use of freopen (see fopen) will cause 
it to become buffered. When an output stream is unbuffered, information is 
queued for writing on the destination file or terminal as soon as written; when 
it is buffered, many characters are saved up and written as a block. When it is 
line-buffered, each line of output is queued for writing as soon as the line is 
completed (that is, as soon as a new-line character is written or input is 
requested). Fflush can also be used to explicitly write the buffer. Setbuf or 
setvbuf maybe used to change the stream's buffering strategy. 

These routines do not have the means to determine if a file is associated with a 
terminal. Therefore, files are fully buffered, except for stdin and stdout which 
are set to line-buffered by the _startup routine and stderr which is not buffered. 

See Also fclose, ferror, fopen, fwrite, getc, fread, printf, puts, setbuf. 
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Diagnostics On success, these functions each return the value they have written. On 

failure, they return the constant EOF. This will occur if the file stream is not 
open for writing or if the output file cannot be increased. 

Line buffering may cause confusion or malfunctioning of programs which use 
standard I/O routines but use read themselves to read from standard input. In 
cases where a large amount of computation is done after printing part of a line 
on an output terminal, it is necessary to filush the standard output before 
going off and computing so that the output will appear. 



Bugs Because it is implemented as a macro, putc treats incorrectly a stream 

argument with side effects. In particular, putc(c, *f+ + ); doesn't work 
sensibly. Fputc should be used instead. 
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puts, fputs 

Put a String on a Stream 



Synopsis 



# include < stdio.h> 

int puts (const char *s); 

int fputs (const char *s, FILE *stream); 



Description Puts writes the null-terminated string pointed to by s, followed by a new-line 

character, to the standard output stream stdout. 

Fputs writes the null-terminated string pointed to by 5 to the named output 
stream . 

Neither function writes the terminating null character. Note that puts appends 
a new-line character, but fputs does not. 

Diagnostics If the routine is successful, puts and fputs both return the number of characters 

written. In the case of puts, the return value includes the implied newline 
character which means that the return value will equal the length of the 
argument string + 1. 



See Also 



ferror, fopen, fread, printf, putc. 
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qsort 

Table Sorting Routine 



Synopsis 



# include < stdlib.h> 



void qsort ( 

void *base, 

size_t nel, size_t size, 

int (*compar)(const void *, const void *)); 

Description Base points to the element at the base of the table. Nel is the number of 

elements in the table. Compar is the name of the comparison function, which 
is called with two arguments that point to the elements being compared. The 
function passed as compar must return an integer less than, equal to, or 
greater than zero as a consequence of whether its first argument is to be 
considered less than, equal to, or greater than the second. This is the same 
return convention that strcmp uses. 



Notes 



The pointer to the base of the table should be of type pointer-to-element, and 
cast to type pointer-to-character. The comparison function need not compare 
every byte, so arbitrary data maybe contained in the elements in addition to 
the values being compared. The order in the output of two items which 
compare as equal is unpredictable. 



See Also 



bsearch. 
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rand, srand 

Simple Random Number Generator 



Synopsis 



# include < stdlib.h> 
int rand (void); 

void srand (unsigned int seed); 



Description 



Rand uses a multiplicative congruential random-number generator with 



32 

period 2 that returns successive pseudo-random numbers in the range from 0 
to2 15 -l. 

Srand can be called at anytime to reset the random-number generator to a 
random starting point. The generator is initially seeded with a value of 1 . 



Note 



The spectral properties of rand leave a great deal to be desired. These 
functions use a global variable to seed the random number generator. Calling 
one of these routines from an interrupt routine will cause the random number 
sequence to be non-repeatable. 
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remove 

Remove a File 

Synopsis # include < stdio.h> 

int remove (const char *filename); 

Description Remove causes the file whose name is the string pointed to by filename to be 

removed. Subsequent attempts to open the file will fail, unless it is created 
anew. If the file is open, the behavior of the remove function is the same as 
unlink. Remove is implemented as a macro and as a function. To use the 
function instead of the macro, # undef the macro before function invocation. 

Return Value Remove returns zero if the operation succeeds, non-zero if it fails. 

See Also fopen, open, unlink. 
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scanf, fscanf, sscanf 

(standard I/O library function) 
Formatted Input from Stream 

Synopsis # include < stdio.h> 

int scanf (const char *format, ...); 

int fscanf (FILE *stream, const char *format, ...) ; 

int sscanf (const char *s, const char *format, ...); 

Description Scanf reads from the standard input stream stdin. Fscanf reads from the 

named input stream. Sscanf reads from the character strings. Each function 
reads characters, interprets them according to a format, and stores the results 
in its arguments. Each expects, as arguments, a control stiingformat described 
below, and a set of pointer arguments indicating where the converted input 
should be stored. 

The control string usually contains conversion specifications, which are used 
to direct interpretation of input sequences. The control string may contain: 

1 White-space characters (blanks, tabs, new-lines, or form-feeds) which 
cause input to be read up to the next non-white-space character. 
White-space in the format string does not mean that white space must 
appear in the input. 

2 An ordinary character (not %), which must match the next character of the 
input stream. 

3 Conversion specifications, consisting of the character % an optional 
assignment suppressing character *, an optional numerical maximum field 
width, an optional 1 (ell), L, or h indicating the size of the receiving 
variable, and a conversion code. 

A conversion specification directs the conversion of the next input field; the 
result is placed in the variable pointed to by the corresponding argument, 
unless assignment suppression was indicated by*. The suppression of 
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assignment provides a way of describing an input field which is to be skipped. 
An input field is defined as a string of non-space characters; it extends to the 
next inappropriate character or until the field width, if specified, is exhausted. 
For all descriptors except "[" and "c", white space leading an input field is 
skipped. 

The conversion code indicates the interpretation of the input field; the 
corresponding pointer argument must usually be of a restricted type. For a 
suppressed field, no pointer argument is given. The following conversion 
codes are legal: 

% A single %is expected in the input at this point; no 

assignment is done. 

d A decimal integer is expected; the corresponding 

argument should be an integer pointer. 

i A signed integer is expected (whose format is the same 

as expected by strtol when its base argument is zero); the 
corresponding argument should be an integer pointer. 

u An unsigned decimal integer is expected; the 

corresponding argument should be an unsigned integer 
pointer. 

o An octal integer is expected; the corresponding 

argument should be an integer pointer. 

x A hexadecimal integer is expected; the corresponding 

argument should be an integer pointer. 

e,f,g A floating point number is expected; the next field is 

converted accordingly and stored through the 
corresponding argument, which should be a pointer to a 
float. The input format for floating point numbers is an 
optionally signed string of digits, possibly containing a 
decimal point, followed by an optional exponent field 
consisting of an E or an e, followed by an optional + or 
- followed by an integer. 

s A character string is expected; the corresponding 

argument should be a character pointer pointing to an 
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array of characters large enough to accept the string and 
a terminating \0, which will be added automatically. 
The input field is terminated by a white-space character. 
Note that scan/cannot read a null string. 

c A character is expected; the corresponding argument 

should be a character pointer. The normal skip over 
white space is suppressed in this case; to read the next 
non-space character, use %ls. If a field width is given, 
the corresponding argument should refer to a character 
array; the indicated number of characters is read. 

[ Indicates string data and the normal skip over leading 

white space is suppressed. The left bracket is followed 
by a set of characters, which we will call the scanset, and 
a right bracket; the input field is the maximal sequence 
of input characters consisting entirely of characters in 
the scanset. The circumflex ( A ), when it appears as the 
first character in the scanset, serves as a complement 
operator and redefines the scanset as the set of all 
characters not contained in the remainder of the scanset 
string. There are some conventions used in the 
construction of the scanset. A range of characters may 
be represented by the construct first-last, thus 
[0123456789] maybe expressed [0-9]. Using this 
convention, first must be lexically less than or equal to 
last, or else the dash will stand for itself. The dash will 
also stand for itself whenever it is the first or the last 
character in the scanset. To include the right square 
bracket as an element of the scanset, it must appear as 
the first character (possibly preceded by a circumflex) of 
the scanset, and in this case it will not be syntactically 
interpreted as the closing bracket. The corresponding 
argument must point to a character array large enough 
to hold the data field and the terminating \0, which will 
be added automatically. At least one character must 
match for this conversion to be considered successful. 

p A hexadecimal number, which should be the same as 

the set of sequences that maybe produced by the %p 
conversion of the printf function. The corresponding 
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argument should be a pointer to a pointer-to-void. For 
any input item other than a value converted earlier 
during the same program execution, the behavior of %p 
is undefined. 

No input is consumed. The corresponding argument 
should be a pointer to integer into which is to be 
written the number of characters read from the input 
stream so far by this call to the scan/function. 
Execution of an %n directive does not increment the 
assignment count returned at the completion of 
execution of the scanf function. 

The conversion characters d, u, o, and x maybe preceded byl or h to indicate 
that a pointer to long or to short rather than to int is in the argument list. 
Similarly, the conversion characters e, f, and g may be preceded by 1 or L to 
indicate that a pointer to double or long double rather than to float is in the 
argument list (long double is equivalent to double with this compiler). The 1, 
h, or L modifier is ignored for other conversion characters. 

Scanf conversion terminates at EOF, at the end of the control string, or when 
an input character conflicts with the control string. In the latter case, the 
offending character is left unread in the input stream. 

Scan/returns the number of successfully matched and assigned input items; 
this number can be zero in the event of an early conflict between an input 
character and the control string. If the input ends before the first conflict or 
conversion, EOF is returned. 

Examples The call: 

int i, n; float x; char name [50]; 
n = scanf ( "%d%f%s" , &i, &x, name) ; 

with the input line: 

25 54.32E-1 thompson 

will assign to n the value 3, to i the value 25, to x the value 5.432, and name will 
contain thompsonM). Or: 
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int i; float x; char name [50]; 

(void) scanf ("%2d%f%*d %[0-9]", &i, &x, name) ; 



with input: 

56789 0123 56a72 

will assign 56 to 789.0 to x, skip 0123, and place the string 56\0 in name. The 
next call to getchar(see getc) will return a. 

See Also getc, printf, strtod, strtol. 

Note Trailing white space (including a new-line) is left unread unless matched in the 

control string. 

Diagnostics These functions return EOF if an input failure occurs before any conversion. 

Otherwise, the number of input items assigned (which maybe fewer than 
provided for, or even zero, in case of an early conflict) is returned. 
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setbuf, setvbuf 

Assign Buffering to a Stream File 

Synopsis # include < stdio.h> 

void setbuf (FILE *stream, char *buf); 

int setvbuf ( 
FILE *stream, 
char *buf, 
int type, 
size_t size); 

Description Setbuf may be used after a stream has been opened but before it is read or 

written. It causes the array pointed to by buf to be used instead of an 
automatically allocated buffer. If buf is the NULL pointer input/output will be 
completely unbuffered. A constant BUFSIZ, defined in the < stdio.h> header 
file, tells how big an array is needed: 

char buf [BUFSIZ] ; 

Setvbuf may be used after a stream has been opened but before it is read or 
written. Type determines how stream will be buffered. Legal values for type 
(defined in stdio.h) are: 

_IOFBF Causes input/output to be fully buffered. 

_IOLBF Causes output to be line buffered. The buffer will be 

flushed when a newline is written, the buffer is full, or 
when input is requested from other streams. 

_IONBF Causes input/output to be completely unbuffered. 

If buf is not the NULL pointer, the array it points to will be used for buffering 
instead of an automatically allocated buffer (from malloc). Size specifies the 
size of the buffer to be used. The constant BUFSIZ in < stdio.h> is suggested 
as a good buffer size. If input/output is unbuffered, buf and size are ignored. 
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By default, all input/output is fully buffered. 
See Also fopen, getc, malloc, putc. 

Diagnostics If an illegal value for type or size is provided, sefvZ?M/returns a non-zero value. 

Otherwise, the value returned will be zero. 

Note A common source of error is allocating buffer space as an "automatic" variable 

in a code block, and then failing to close the stream in the same block. 
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setjmp, longjmp 

Non-Local Goto 

Synopsis # include < setjmp.h> 

int setjmp (jmpjbuf env); 

void longjmp (jmpjbuf env, int val); 

Description These functions are useful for dealing with errors and interrupts encountered 

in a low-level subroutine of a program. 

Setjmp saves its stack environment in env (whose type, jmp_buf, is defined in 
the < setjmp.h> header file) for later use by longjmp. It returns the value 0. 

Longjmp restores the environment saved by the last call of setjmp with the 
corresponding env argument. After longjmp is completed, program execution 
continues as if the corresponding call of setjmp had just returned the value val. 
Longjmp cannot cause setjmp to return the value 0. If longjmp is invoked with 
a second argument of 0, setjmp will return 1. 

All globally accessible objects have values as of the time longjmp was called. 
All automatics local to the destination stack frame have values as of the time 
setjmp was called, provided none were modified after calling setjmp; if 
modified, the value of an automatic is undefined. 

If a longjmp is executed and the environment in which the setjmp was executed 
no longer exists, errors can occur. The conditions under which the 
environment of the setjmp no longer exists include: exiting the procedure 
which contains the setjmp call, and exiting an inner block with temporary 
storage (e.g., a block with declarations in C, a with statement in Pascal). This 
condition may or may not be detectable. An attempt is made by determining if 
the stack frame pointer in env points to a location not in the currently active 
stack. If this is the case, longjmp will return a -1. Otherwise, the longjmp will 
occur, and if the environment no longer exists, the contents of the temporary 
storage of an inner block are unpredictable. This condition may also cause 
unexpected process termination. If the procedure has been exited the results 
are unpredictable. 
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Passing longjmp a pointer to a buffer not created by setjmp, or a buffer that has 
been modified by the user, can cause all the problems listed above, and more. 

Warning If longjmp is called even though env was never primed by a call to setjmp, or 

when the last such call was in a function which has since returned, absolute 
chaos is guaranteed. 
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setlocale 

Locale Control 



Synopsis 



# include < locale.h> 

char *setlocale (int category, const char *locale); 



Description 



Setlocale selects the appropriate piece of the program's locale as specified by 
the category and locale arguments. Setlocale maybe used to read or modify all 
or part of the program's current locale. Using LC_ALL for category specifies 
the program's entire locale. Other values for category name only a part of the 
program's locale. LC_COLLATE affects the behavior of the strcoll function. 
LC_TYPE affects the behavior of the character handling functions. 
LC_NUMERIC affects the decimal-point character for the formatted 
input/output functions (printf, scanf, etc.) and the string conversion functions 
(strtod, strtol, etc.). 

A value of "C" for locale specifies the minimal environment for C translation; a 
value of " " for locale is equivalent to "C". At present, the only locale that is 
implemented is "C". 

At program startup, the equivalent of 

setlocale ( LC_ALL, "C" ) ; 

is executed. 



Diagnostics If a pointer to a string is given for locale and the selection can be honored, the 

setlocale function returns the string associated with the specified category for 
the new locale. If the selection cannot be honored, the setlocale function 
returns a null pointer, and the program's locale is not changed. 

A null pointer for locale causes the setlocale function to return the string 
associated with the category for the program's current locale; the program's 
locale is not changed. This inquiry can fail by returning a null pointer only if 
the category is LC_ALL and the most recent successful locale-setting call used 
a category other than LC_ALL. 
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The string returned by the setlocale function is such that a subsequent call with 
that string and its associated category will restore that part of the program's 
locale. The string returned shall not be modified by the program, but maybe 
overwritten by a subsequent call to the setlocale function. 

See Also localeconv, strtod, strtol, printf, scanf, strcoll, strxfrm. 
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sin, cos, tan, asin, acos, atan, atan2 



Trigonometric Functions 



Synopsis 



# include < math.h> 

double sin (double x); 

double cos (double x); 

double tan (double x); 

double asin (double x); 

double acos (double x); 

double atan (double x); 

double atan2 (double y, double x) ; 



Description Sin, cos and tan return respectively the sine, cosine, and tangent of their 

argument, x, measured in radians. 

The approximate limit for the values passed to these functions is 2.98E8 for sin 
and cos, and 1.49E8 for tan. 

Asin returns the arcsine of x, in the range -7l/2 to Jt/2. 

Acos returns the arccosine of x, in the range 0 to 71. 

Atan returns the arctangent ofx, in the range -Jt/2 to jc/2. 

Atan2 returns the arctangent ofy/x, in the range -71 to 7C, using the signs of 
both arguments to determine the quadrant of the return value. 



Diagnostics Sin, cos, and tan lose accuracy when their argument is far from zero. For 

arguments sufficiently large, these functions return zero when there would 
otherwise be a complete loss of significance, errno is set to ERANGE. 
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If x is greater than one for asin or acos, a Not-a-Number (NaN) is returned. If 
both arguments for atanl are zero, 0.0 is the result. Errno is set to EDOM for 
both of these conditions. 

Error actions are determined by the bits of a global control flag (see the 
_fp_error description). 

See Also _fp_error, "Behavior of Math Library Functions" chapter. 
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Synopsis 



Description 



Diagnostics 



See Also 



sinh, cosh, tanh 

Hyperbolic Functions 

# include < math.h> 
double sinh (double x); 
double cosh (double x); 
double tanh (double x); 



Sinh, cosh, and tanh return, respectively, the hyperbolic sine, cosine, and 
tangent of their argument. These are double-precision routines. 



Sinh and cosh set errno to ERANGE and return HUGE_VAL (sinh may return 
-HUGE_VAL for negative x) when the correct value would overflow. 

These error-handling procedures maybe changed with the function _fp_error. 



fp_error, "Behavior of Math Library Functions" chapter. 



218 



Chapter 7: Libraries 

sqrt 



sqrt 

Square Root Function 



Synopsis 



# include < math.h> 
double sqrt (double x); 



Description Sqrt returns the non-negative square root of x. The value of x may not be 

negative. 

Diagnostics Sqrt returns a NaN and sets errno to EDOM when x is negative. The error 

action is determined by the bits of a global control flag. 

These error-handling procedures maybe changed with the function _fp_error. 



See Also 



_fp_error, "Behavior of Math Library Functions" chapter. 
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strcat, strncat, ... 

String Operations 

Synopsis # include < string.h> 

char *s treat (char *sl, const char *s2); 

char *strncat (char *sl, const char *s2, size_t n); 

int strcmp (const char *sl, const char *s2); 

int strncmp (const char *sl, const char *s2, size_t n); 

int strcoll (const char *sl, const char *s2); 

char *strcpy (char *sl, const char *s2); 

char *strncpy (char *sl, const char *s2, size_t n); 

char *strerror (int errnum); 

size_t strlen (const char *s); 

char *strchr (const char *s, int c); 

char *strrchr (const char *s, int c); 

char *strpbrk (const char *sl, const char *s2); 

size_t strspn (const char *sl, const char *s2); 

size_t strcspn (const char *sl, const char *s2); 

char *strstr (const char *sl, const char *s2); 

char *strtok (char *sl, const char *s2); 
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Description These functions operate on null-terminated strings. The arguments si, s2 and 

s point to strings (arrays of characters terminated by a null character). The 
functions strcat, strncat, strcpy, and strncpy all alter si. These functions do not 
check for overflow of the array pointed to by si. 

Strcat appends a copy of string s2 to the end of string si. Strncat appends at 
most n characters. It copies less if s2 is shorter than n characters. Each 
returns a pointer to the null-terminated result (the original value of si). 

Strcmp compares its arguments and returns an integer less than, equal to, or 
greater than 0, according as si is lexicographically less than, equal to, or 
greater than s2. Strncmp makes the same comparison but looks at most n 
characters (n less than or equal to zero yields equality). Both of these routines 
use unsigned char for character comparison. 

The strcoll function returns an integer greater than, equal to, or less than zero, 
according to whether the string pointed to by si is greater than, equal to, or 
less than the string pointed to by s2. The comparison is based on strings 
interpreted as appropriate to the program's locale. 

Strcpy copies string s2 to si, stopping after the null character has been copied. 
Strncpy copies exactly n characters, truncating s2 or adding null characters to 
si if necessary. The result will not be null-terminated if the length of s2 is n or 
more. If the length of s2 is less than n, characters from the first null in s2 to 
the nth character are copied as nulls. Each function returns si. 

Note that strncpy should not be used to copy n bytes of an arbitrary structure. 
If that structure contains a null byte anywhere, strncpy will terminate the copy 
when it encounters the null byte, thus copying fewer than n bytes. Use the 
nxcnxcpy function for these cases. 

Strerror maps the error number in errnum (returned from errno) to an error 
message string. Strerror returns a pointer to the string, the contents of which 
describe the meaning of the error number. The array pointed to must not be 
modified by the program. 

Strlen returns the number of characters in s, not including the terminating null 
character. 

Strchr (strrchr) returns a pointer to the first (last) occurrence of character c (an 
8-bit ASCII value) in string s, or a NULL pointer if c does not occur in the 
string. The null character terminating a string is considered to be part of the 
string. 
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Strpbrk returns a pointer to the first occurrence in string si of any character 
from string s2, or a NULL pointer if no character from s2 exists in si. 

Strspn (strcspn) returns the length of the initial segment of string si which 
consists entirely of characters from (not from) string s2. 

Strstr locates the first occurrence in the string pointed to by si of the sequence 
of characters (excluding the terminating null character) in the string pointed 
to by s2. Strstr returns a pointer to the located string, or a null pointer if the 
string is not found. If the second argument, s2, has a length of zero, then strstr 
returns the first argument as the return value. 

Strtok considers the string si to consist of a sequence of zero or more text 
tokens separated by spans of one or more characters from the separator string 
s2. The first call (with pointer si specified) returns a pointer to the first 
character of the first token, and will have written a null character into si 
immediately following the returned token. The function keeps track of its 
position in the string between separate calls, so that subsequent calls (which 
must be made with the first argument a NULL pointer) will work through the 
string si immediately following that token. In this way subsequent calls will 
work through the string si until no tokens remain. The separator string s2 
maybe different from call to call. When no token remains in si, a NULL 
pointer is returned. 

Since the strtok function must keep track of its position in the input string, this 
function cannot be made reentrant. 

Note For user convenience, all these functions are declared in the optional 

< string.h> header file. 

Bugs The copy operations cannot check for overflow of any receiving string. NULL 

arguments cause undefined behavior. 

Character movement is performed differently in different implementations. 
Memmove should be used for overlapping moves. 
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strtod, atof 

String to Double-Precision Number 



Synopsis 



# include < stdlib.h> 

double strtod (const char *str, char **ptr); 
double atof (const char *str); 



Description Strtod returns as a double -precision floating-point number the value 

represented by the character string pointed to by str. The string is scanned up 
to the first unrecognized character. 

Strtod recognizes an optional string of "white-space" characters (as defined by 
isspace), then an optional sign, then a string of digits optionally containing a 
decimal point, then an optional e or E followed by an optional sign, followed 
by an integer. 

If the value of ptr is not (char **)NULL, the variable to which it points is set 
to point at the character after the last number, if any, that was recognized. If 
no number can be formed, *ptr is set to str, and zero is returned. 

Atoffstr) is equivalent to strtod(str, (char **)NULL). 



See Also 
Diagnostics 



scanf, strtol. 



If the correct value would cause overflow, + /-HUGE_VAL is returned 
(according to the sign of the value), and errno is set to ERANGE. If the correct 
value would cause underflow, zero is returned and errno is set to ERANGE. 
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strtol, strtoul, atol, atoi 

Convert String to Integer 

Synopsis # include < stdlib.h> 

long strtol (const char *str, char **ptr, int base); 

unsigned long strtoul ( 
const char *str, 
char **ptr, 
int base); 

long atol (const char *str); 
int atoi (const char *str); 

Description Strtol returns as a long integer the value represented by the character string 

pointed to by str. The string is scanned up to the first character inconsistent 
with the base. Leading "white-space" characters (as defined by isspace in 
ctype.h) are ignored. 

If the value of/?fris not (char **)NULL, a pointer to the character terminating 
the scan is returned in the location pointed to by ptr. If no integer can be 
formed, that location is set to str, and zero is returned. 

If base is positive (and not greater than 36), it is used as the base for 
conversion. After an optional leading sign, leading zeros are ignored, and "Ox" 
or "OX" is ignored if base is 16. 

If base is zero, the string itself determines the base as follows: After an 
optional leading sign a leading zero indicates octal conversion, and a leading 
"Ox" or "OX" hexadecimal conversion. Otherwise, decimal conversion is used. 

Strtoul is the same as strtol except that no leading plus or minus is allowed in 
the string pointed to by str. 

Atol(str) is equivalent to strtol(str, (char **)NULL, 10). 
Atoi(str) is equivalent to (int) strtol(str, (char **)NULL, 10). 
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See Also atof, ctype, scanf, strtod. 

Bugs Overflow conditions are ignored. 



225 



Chapter 7: Libraries 

toupper, tolower, Joupper, _to lower 



toupper, tolower, Joupper, Jolower 

Translate Characters 



Synopsis 



# include < ctype.h> 
int toupper (int c); 
int tolower (int c); 
int _toupper (int c); 
int _tolower (int c) ; 



Description Toupper and tolower have as domain the range of getc: the integers from -1 

through 255. If the argument of toupper represents a lower-case letter, the 
result is the corresponding upper-case letter. If the argument of tolower 
represents an upper-case letter, the result is the corresponding lower-case 
letter. All other arguments in the domain are returned unchanged. Toupper 
and tolower are implemented both as macros and functions. To use a function 
instead of a macro, # undef the macro before function invocation. 

The macros _toupper and _tolower accomplish the same thing as toupper and 
tolowerbut have restricted domains and are faster. Joupper requires a 
lower-case letter as its argument; its result is the corresponding upper-case 
letter. The macro _tolower requires an upper-case letter as its argument; its 
result is the corresponding lower-case letter. Arguments outside the domain 
cause undefined results. Use of this form will never work with foreign 
character sets. 



See Also 



getc. 
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ungetc 



Push Character Back into Input Stream 



Synopsis 



# include < stdio.h> 

int ungetc (int c, FILE *stream); 



Description Ungetc inserts the character c into the buffer associated with an input stream. 

That character, c, will be returned by the next getc call on that stream. Ungetc 
returns c, and leaves the file stream unchanged. 

One character of pushback is guaranteed, provided something has already 
been read from the stream and the stream is actually buffered. In the case that 
stream is stdin, one character maybe pushed back onto the buffer without a 
previous read statement. 

If c equals EOF, ungetc does nothing to the buffer and returns EOF. 
Fseek erases all memory of inserted characters. 



See Also 
Diagnostics 



fseek, getc, setbuf. 



Ungetc returns EOF if it cannot insert the character. 
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vajist, va_start, va_arg, va_end 



Synopsis # include < stdarg.h> 

vajist 

void va_start( vajist list, arg_n) 
type va_arg( vajist list, type) 
void va_end( vajist list) 



Description The preceding macros are used for functions that have variable numbers of 

arguments. The type vajist is used to track which of the optional arguments 
are being processed. 

The va_start macro is used to initialize the variable of type vajist. Its second 
argument, arg_n, is the last of the non-optional arguments of the current 
function. The type of arg_n must be of the default argument promotion types 
(int, long, double; not char, short, enum, or float). 

The va_arg macro evaluates to the value of the next optional argument from 
when the function was invoked. Each successive call to va_arg gives the next 
argument that was given. The second argument to va_arg is the type of the 
argument that was passed next in the list. Again this type should only be from 
the set of default argument promotion types (int, long, double, pointers, and 
structures). Using a type of short, char, enum, or float will cause undefined 
behavior because these types can not be passed as optional arguments. 

The va_end macro should be called when the last of the optional arguments 
has been processed. This ensures proper termination of the optional 
argument processing. 

Example The following function takes a variable number of arguments that are all of 

type integer. The function returns the sum of all of the optional arguments. 

#include <stdarg.h> 
int 

sum (int count, ...) 
{ 

va_list args; 

int result = 0 ; 
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va_start (args, count); 
while (count — > 0) 

result += va_arg (args, int); 
va_end (args) ; 
return result; 
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vprintf, vfprintf, vsprintf 

Formatted Output of Varargs List 

Synopsis # include < stdio.h> 

# include < stdarg.h> 

int vprintf (const char *format, va_list ap); 

int vfprintf ( 
FILE *stream, 
const char *format, 
va_list ap); 

int vsprintf ( 
char *s, 

const char *format, 
va_list ap); 

Description Vprintf, vfprintf, and vsprintf are. the same as printf fprintf and sprintf 

respectively, except that instead of being called with a variable number of 
arguments, they are called with an argument list as defined by stdargs.h. 
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Example The following demonstrates how vfprintf could be used to write an error 

routine. 

#include <stdio.h> 
#include <stdarg.h> 

/* "error" should be called like: 

* error (f unction_name, format, argl, arg2 . . . ) ; */ 

void 

error (char *f unction_name, char *format, ...) 
{ 

va_list args; 

va_start (args, format); 

/* print out name of function causing error */ 
(void) fprintf (stderr, "ERROR in %s: ", function_name) ; 
/* print out remainder of message */ 
(void) vfprintf (stderr, format, args); 
va_end (args ) ; 
exit (1) ; 

} 



See Also printf, stdarg.h. 
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vprintf, vfprintf, vsprintf 
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8 



Environment-Dependent Routines 

Description of the emulator environment-dependent routines. 
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This chapter describes the HP emulator execution environment-dependent 
routines. The source files for these interface routines (as well as the object 
code files) are provided so they can be customized for target system execution 
environments. 

The environment-dependent routines (except monitor and mon_stub) and 
library functions are all located in linker segment name env. This segment 
name maybe used just as any other segment name would be (for example, in 
SEGMENT pragmas). See the on-line man pages for a complete description of 
the cc8086 and cc80186 command syntax and options. 

The environment-dependent routines relate to the following areas of C 
programming. 

• Program Setup. 

• Dynamic Memory Allocation. 

• Program Input and Output. 
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Program Setup 

Two program setup routines are provided with the 8086/186 C compiler. 
crtO.o For programs which use I/O . 

crtl.o For programs which do not use I/O. 

These routines define the entry point for program setup, entry(), and are 
responsible for general preexecution setup such as initialization of the stack 
pointer. At the end of preexecution initialization, these setup routines call 
main(). 

The source files of the program setup routines have been provided (and are 
well commented) in case they need to be rewritten, for example, to change any 
of the default initializations or to add any new program setup such as 
establishing values other than zero for argv and argc. 

Differences Between "crt0"and "crt1" 

The difference between the two program setup routines is that crtO will call 
the _startup() library routine to open the standard input, output, and error 
files: stdin, stdout, and stderr. The crtl routine does not open the standard 
input, output, and error streams and has been provided to avoid the overhead 
of loading the stdio library for a program which doesn't use it. 

When using crtl instead of crtO, the behavior of the exit() and _exit() library 
routines is different. Since crtl is used in non-I/O applications, neither exit() 
nor _exit() will flush buffers or close open files. The exit() routine simply 
executes functions which have been logged by the atexit() routine, and the 
_exit() routine just calls _exit_msg(). 
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The "_display_message()" Routine 

The _display_message() routine displays run-time error messages. A call to 
_display_message() guarantees program termination. The 
_display_message() routine is called from _exit() (via _exit_msg()) and other 
library routines; it is also called by the code generated when the "generate 
run-time error checking" command line option is specified. 

The _display_message() routine causes the emulation monitor program to 
display a message on the emulation display's STATUS line. 

An example of how the _display_message() routine is called can be found in 
the startup.c source file. 

Linking the Program Setup Routines 

The program setup routines are loaded, respectively, by the following linker 
command files. 

iolinkcom.k Links program with crtO.o. 

linkcom.k Links program with crtl.o. 

fiolinkcom.k Links program containing 8087 code with crtO.o. 

flinkcom.k Links program containing 8087 code with crtl.o. 

Since C assumes that stdin, stdout, and stderr are opened prior to main() 
being called, cc8086 automatically uses the iolinkcom.k (or fiolinkcom.k) 
linker command file. To link with crtl.o instead, use the cc8086 "no I/O" 
option to specify that the linkcom.k (or flinkcom.k) command file be used. 

If you use the "generate code for the 8087" (-f) option, fiolinkcom.k or 
flinkcom.k will be used instead of iolinkcom.k or linkcom.k. These linker 
command files substitute lib87.a for lib.a and libm87.a for libm.a. 

Whenever the environment-dependent library, env.a, is modified, you must 
also modify the default linker command file to load the new library. 

Emulator Configuration Files 

Two to four configuration files are provided for each supported emulator: 
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ioconfig.EA 



For programs linked with crtO.o. 



config.EA 



For programs linked with crtl.o. 



fioconfig.EA 



For programs containing 8087 code and linked with 
crtO.o. 



fconfig.EA 



For programs containing 8087 code and linked with 
crtl.o. 



Polling for simulated I/O is enabled by the ioconfig.EA and fioconfig.EA files 
because the stdin, stdout, and stderr streams (which are set up by the crtO 
routine) are implemented via simulated I/O in the emulation environment. 
The config.EA and fconfig.EA files do not enable polling for simulated I/O 
because crtl does not set up the standard input, output, and error streams. 

Configuration files fioconfig.EA and fconfig.EA are supplied only for those 
emulation environments which support the 8087. These configuration files 
should be used whenever the program contains 8087 code. 
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Memory Map 

Notice that each memory model has its own memory map. Check figures 8-3 
and 8-4 (figures 8-5 and 8-6 for HP 647xx emulation environments) to find out 
where the segments are placed for a particular memory model. The segment 
ordering is specified by the default linker command files iolinkcom.k and 
linkcom.k (fiolinkcom.k and flinkcom.k when using the 8087). The memory 
map is defined by the provided emulator configuration files ioconfig.EA and 
config.EA (fioconfig.EA and fconfig.EA when using the 8087). Because 
emulator configuration files map memory for absolute code located by the 
linker, modifications to the default linker command files will usually 
necessitate modifications to the emulator configuration as well. 



Note When using small memory model with the run-time error checking option 

turned on, no user code (PROG Segment prog/CODE) or data (DATA 
Segment data) should be placed where OFFSET = 0000. The NULL pointer 
is defined to be 0000. If you store code or data at OFFSET 0000, the address 
of that code or data will be confused with the NULL pointer. 

Note that the small memory model map has the PROG and DATA segments 
beginning at 80002H and 10002H to avoid this situation. 
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00000H 
(emulROM) 
003FFH 



SEGMENT interrupt 
(IK) 



Space reserved for interrupt 
vectors. 



10000H 



(emul RAM) 



1F3FFH 



• 

SEGMENT envdata 
SEGMENT libdata 
SEGMENT libcdata 
SEGMENT data 
SEGMENT idata 
SEGMENT udata 
SEGMENT heap (4K) 
SEGMENT userstack 
(61K) 



Environment-dependent data 
Run-time library data 
Support library data 
Default for user data 
Initialized user data 
Uninitialized user data 
System dynamic pool 
System stack 



80000H 



(emul ROM) 



8FFFFH 



FFFFFH 



• 

CLASS CODE 
SEGMENT libcconst 
SEGMENT libmconst 

CLASS ??INIT 
SEGMENT mm_check 
SEGMENT const 
(64K) 

• 



All code space 
Support library constants 
Math library constants 
Initialized-data tables 
Memory model check 
Default for user constants 



Figure 8-1 . Default Memory Map for Large Memory Model 
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00000H 
(emul ROM) 
003FFH 



SEGMENT interrupt 
(IK) 



Space reserved for interrupt 
vectors. 



10002H 



(emul RAM) 



1F3FFH 



• 

SEGMENT data 
SEGMENT idata 
SEGMENT udata 
SEGMENT heap (4K) 
SEGMENT userstack 

SEGMENT const 
SEGMENT envdata 
(61K) 



Library & default user data 
Initialized user data 
Uninitialized user data 
System dynamic pool 
System dynamic stack 
User constants 
INITDATA data 



80002H 
(emul ROM) 
8FFFFH 



• 

CLASS CODE 
CLASS ??INIT 
SEGMENT mm_check 
(64K) 



All code space 
Initialized-data tables 
Memory model check 



FFFFFH 



Figure 8-2. Default Memory Map for Small Memory Model 
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Dynamic Allocation 

There are several dynamic allocation routines in the libc.a support library 
(e.g., malloc, realloc, etc.). The only environment dependency is isolated in 
the function _getmem(). For these dynamic allocation routines to work, the 
function _getmem() must return memory allocated from the system. The 
source for the _getmem() function is provided in the "shipped sources" 
directory. 

As provided, _getmem() returns an address to a block of dynamic memory and 
the size of that block. If the block size requested bymalloc() cannot be 
satisfied, the largest block left in the heap will be returned. The calling 
sequence is: 

void *_getmem ( int *size); 
ptr = _getmem ( &size ); 

The size of the block allocated, whether it is larger or smaller than the size 
requested, is returned indirectly through the pointer parameter. Calling 
_getmem() with a size equal to zero will cause the current address of the heap 
to be returned. 

If desired, _getmem() maybe written to return more than the requested 
amount of memory; the dynamic allocation routines will take advantage of this. 

Rewriting the "jgetmem" Function 

This routine (in file getmem.c) should be rewritten to return memory in the 
best way for the target system. In a simple embedded system this routine 
should probably be written to return the address of an array big enough to use 
up all available RAM not used by the rest of the program. If an operating 
system is present, the routine should be written to return a large chunk of 
memory from the operating system at each call. This routine is similar to the 
host operating system sbrk() function. 

After the _getmem() function is rewritten and compiled, the new getmem.o 
object file should be loaded before the env.a library, or be used (with ar86) to 
replace the existing getmem object module in the env.a library. Refer to the 
"Getting Started" chapter for an automated way to rebuild the env.a library 
using the make utility. 
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Input and Output 

Many of the functions defined by stdio.h use the basic I/O functions found in 
the systemio support library module. These basic I/O functions are: open(), 
close(), read(), write(), lseek(), and unlink(). The systemio functions provided 
use the simulated I/O feature of the emulation environments. The C source 
code for the basic I/O functions is provided in the "shipped sources" directory. 

As provided, the I/O system defines the maximum number of I/O control 
blocks available as 12 (which equals the maximum number of simulated I/O 
files that can be open at the same time), and the size of the I/O buffers is 
defined to be 1020 bytes (based on the 255 byte size of the simulated I/O 
buffer). These values can be changed by redefining the macros FOPEN_MAX 
and BUFSIZ in the header file stdio.h; after the values of these macros are 
changed, you must recompile the file startup.c. Changes to FOPEN_MAX and 
BUFSIZ will not take effect until a new startup.o object file is made and 
placed in the environment dependent library, env.a. 

The systemio.c file should be rewritten for the target system environment. 

After the systemio.c file is rewritten and compiled, the new systemio.o object 
file should either be loaded before the env.a library, or be used (with ar86) to 
replace the existing systemio object module in the env.a library. Refer to the 
"Getting Started" chapter for an automated way to rebuild the env.a library 
using the make utility. 

Environment-Dependent I/O Functions 

The remainder of this chapter describes the I/O library functions which are 
dependent on the emulator execution environments. Functions declared in the 
simio.h include file are found in the environment-dependent library archive 
file env.a. 
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clear screen 



clear_screen 

Clear the Simulated I/O Display 

Synopsis # include < simio.h> 

int clear_screen (int fildes); 

Description Clear_screen clears the simulated I/O display if stdout is directed to the display. 

Fildes is the file descriptor obtained from an open system call to open stdout. 

Errors Clear_screen will fail and the display will not be cleared if one of the following 

conditions is true; errno will be set accordingly. 

[INVALID_CMD] 

Attempt to clear the display on a file that is not a 
display. 

[INVALID_DESC] 

Fildes is not an open file descriptor. 
[CONTINUE_ERROR] 

Attempt to clear the display after a continued 
emulation session (emulation is exited and then 
reentered). 

Return Value Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 

is returned and errno is set to indicate the error. 
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close 

close 

Close a File Descriptor 

Synopsis # include < simio.h> 

int close (int Hides); 

Description Fildes is a file descriptor obtained from an open system call. Close closes the 

file indicated by fildes. 

Errors Close will fail and the file will not be closed if one of the following conditions 

is true; errno will be set accordingly. 

[INVALID_DESC] 

Fildes is not an open file descriptor. 
[CONTINUE_ERROR] 

Attempt to close any file descriptor after a continued 
emulation session (emulation is exited and then 
reentered). 

[UNIX_ERROR] 

Any error from the host operating system close(2) 
function. 

Return Value Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 

is returned and errno is set to indicate the error. 

See Also open. 
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exec cmd 



exec_cmd 

Execute Operating System Command on the Host 



Synopsis 



# include < simio.h> 

int exec_cmd ( 

const char *command, 

int *filel, 

int *ffle2, 

int *file3); 



Description Exec_cmd executes an operating system command on the host computer. 

Command is a pointer to a string composed of the command to be executed 
and any parameters required by that command. Filel,file2, and file3 are 
pointers to variables which will be set to the file descriptors of the pipes 
connected to stdin, stdout, and stderr of the process spawned. If any pointer is 
NULL, that pipe is connected to /dev/null and no file descriptor is returned. 



Errors Exec_cmd will fail and the command will not be executed if one of the 

following conditions is true; errno will be set accordingly. 

[CANNOT_READ_MEMORY] 

Read of command name failed. 

[NO_FREE_DESC] 

The simulated I/O descriptor table is full. 
[TOO _M AN Y_F ILE S] 

Host pipe(2) command failed. 
[NO_FREE_PROC_ID] 

The maximum number of processes are already active. 
[TOO_MANY_PROCESSES] 
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exec cmd 



Host fork(2) failed and errno = EAGAIN. 
[INVALID_CMD_NAME] 

The command name length is zero. 

[UNIX_ERROR] 

Host fork(2) failed and errno does not equal EAGAIN. 

Return Value Upon successful completion, a process ID number > = 0, and the pipes' file 

descriptors are returned. Otherwise, a value of -1 is returned and errno is set 
to indicate the error. 
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exit, _exit 



exit, _exit 

Terminate Process 



Synopsis 



# include < stdlib.h> 
void exit (int status); 
void _exit (int status); 



Description Exit is equivalent to _exit, except that exit flushes stdio buffers, while _exit does 

not. Also, exit executes any routines that have been logged by the atexit 
routine; _exit does not do this. Both exit and _exit terminate the calling 
process by closing all open file descriptors. _display_message( ) is called via 
_exit_msg(), with the message: "Prog end, returned < arg> ", where "arg" is 
either the value returned by main() or the argument passed to an explicit call 
to exit. 

When programs are not linked with the I/O routines (the "no I/O" command 
line option is used), the behavior is the same as above except that exit does not 
flush stdio buffers, and neither function closes open file descriptors. 



See Also 



atexit. 
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_getmem 



jgetmem 



Get Block of Memory from System Heap 



Synopsis 



# include < memory.h> 
void *_getmem(int *size); 



Description _getmem is called by the support library dynamic allocation routines (e.g., 

malloc, realloc, etc.) and the sbrk function. For these functions to work, 
_getmem must return memory allocated from the system. 

_getmem returns an address to a block of dynamic memory and the size of that 
block. If the block size requested by malloc cannot be satisfied, the largest 
block left in the heap will be returned. Size can be negative, in which case the 
amount of allocated space is decreased. 

Return Value The size of the block allocated, whether it is larger or smaller than the size 

requested, is returned indirectly through the pointer parameter. Calling 
_getmem with a size equal to zero will cause the current address of the heap to 
be returned. 

If desired, _getmem maybe rewritten to return more than the requested 
amount of memory; the dynamic allocation routines (e.g., malloc, realloc, etc.) 
will take advantage of this. 



Warnings 



Deallocating memory (calling _getmem with a negative size) without first 
having allocated the memory will cause unknown results. 
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_getmem 



Example An example of how the _getmem function is used can be found in the shipped 

source file sbrkx shown below. 

#include <memory . h> 

tpragma SEGMENT PROG=env DATA=envdata CONST=env 
extern void *_getmem { ) ; 

void 

*sbrk( incr ) 
int incr; 



{ 



void *ptr; /* pointer to memory block allocated */ 

char *tptr; /* used to zero memory block allocated */ 

int size = incr; 

ptr = _getmem { Ssize ) ; 

if ( size != incr ) /* was request satisfied? */ 

{ 

size = -size; /* free block returned by _getmem since */ 

_getmem ( Ssize ); /* did not satisfy request. */ 

return (char *)-l; 

} 

/* initialize memory block to be returned to zero */ 
for ( tptr = ptr; tptr < (char *)ptr+incr; tptr++ ) 

*tptr =0; 
return ptr; 



See Also malloc, free, realloc, calloc, sbrk. 
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initsimio 



initsimio 



Initialize Simulated I/O 



Synopsis # include < simio.h> 

int initsimio (void); 

Description It is not necessary to call the initsimio function prior to calling any other 

functions implemented via simulated I/O; however, doing so will allow you to 
restart a program, which was stopped with simulated I/O files still open, 
without any side effects from the previously opened files. 

Return Value Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 

is returned and errno is set to indicate the error. 
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kill 



kill 

Kill Simulated I/O Process 

Synopsis # include < simio.h> 

int kill (int pid, int sig); 

Description Kill sends signal sig to a process running on the host which is identified by the 

process ID number pid. 

Errors Kill will fail and the process will not be killed if one of the following conditions 

is true; errno will be set accordingly. 

[NO_PERMISSION] 

Host kill(2) failed because of a permissions error. 
[INVALID_PROC_ID] 

The simulated I/O process ID is unused or out of range 
(the simulated I/O process entry does not exist). 

[INVALID_SIGNAL] 

Host kill(2) failed because sig is not a valid signal. 
[NO_SUCH_PROCESS] 

The host operating system process does not exist. 

[UNIX_ERROR] 

Host kill(2) failed for some other reason. 

Return Value Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 

is returned and errno is set to indicate the error. 
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Iseek 



Iseek 

Move Read/Write File Pointer 



Synopsis # include < simio.h> 

# include < stdio.h> 



long Iseek (int Hides, long int offset, int whence); 



Description Fildes is a file descriptor returned from a open system call. Lseek sets the file 

pointer associated with fildes as follows. (The SEEK_* macros are defined in 
<stdio.h> which must be included.) 

If whence is SEEK_SET, the pointer is set to offset bytes. If whence is 
SEEK_CUR, the pointer is set to its current location plus offset. If whence is 
SEEK_END, the pointer is set to the size of the file plus offset. 

Upon successful completion, the resulting pointer location, as measured in 
bytes from the beginning of the file, is returned. 

Lseek will fail and the file pointer will remain unchanged if one or more of the 
following are true: 

[INVALID_DESC] 



Fildes is not an open file descriptor. 
[NO_SEEK_ON_PIPE] 

Fildes is associated with a pipe or fifo. 
[INVALID_OPTIONS] 

Whence is any illegal value. 
[INVALID_OPTIONS] 



The resulting file pointer would be negative. 
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Iseek 



[INVALID_CMD] 

Fildes is display or keyboard. 
[CONTINUE_ERROR] 



Attempt to move a file pointer after a continued 
emulation session (emulation is exited and then 
reentered). 



[UNIX_ERROR] 



Some host operating system call has failed. Some 
devices are incapable of seeking. The value of the file 
pointer associated with such a device is undefined. 

Return Value Upon successful completion, a non-negative integer indicating the file pointer 

value is returned. Otherwise, a value of -1 is returned and errno is set to 
indicate the error. 

See Also open. 
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open 



open 

Open File for Reading or Writing 

Synopsis # include < simio.h> 

int open (const char *path, int option); 

Description Open requests the host to open a file specified bypath with the given options. 

If the operation is successful, open will return a valid file descriptor. If 
unsuccessful, open will set errno and return -1. Option values are constructed 
by OR-ing flags from the list below. 

Open for reading only. 

Open for writing only. 

Open for reading and writing. 

This flag may affect subsequent reads and writes. 

If set, the file pointer will be set to the end of the file 
prior to each write. 

If the file exists, this flag has no effect. Otherwise, the 
file is created, the owner ID of the file is set to the 
effective user ID of the process, and the group ID of the 
file is set to the effective group ID of the process. 

If the file exists, its length is truncated to 0 and the 
mode and owner are unchanged. 

If O.EXCL and O.CREATE are set, open will fail if 
the file exists. 




O.READ 
() WRITE 
O.RDWR 
O.NDELAY 
0_APPEND 

O.CREATE 



O.TRUNC 



O.EXCL 
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open 



Errors Open will fail and the file will not be opened if one of the following conditions 

is true. Errno will be set accordingly: 

[UNIX_ERROR] 

A component of the path prefix is not a directory, or, 

The named file is a directory and option is write or 
read/write, or, 



The named file resides on a read-only file system and 
option is write or read/write, or, 

The named file is a character special or block special 
file, and the device associated with this special file does 
not exist, or, 

The file is open for execution and option is write or 
read/write. Normal executable files are only open for a 
short time when they start execution. Other executable 
file types maybe kept open for a long time, or 
indefinitely under some circumstances, or, 

A signal was caught during the open system call, or, 
The system file table is full. 



[FILE_NOT_FOUND] 

0_CREATE is not set and the named file does not exist. 

[NO_PERMISSION] 

A component of the path prefix denies search 
permission, or, 



Option permission is denied for the named file. 



[TOO_MANY_FILES] 

More than the maximum number of file descriptors are 
currently open. 

[FILE_EXISTS] 

O.CREATE and O.EXCL are set, and the named file 
exists. 
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open 



[INVALID_FILE_NAME] 

Path is null. 

[INVALID_OPTIONS] 

Option specifies both O.WRITE and O.RDWR. Also, 
undefined bits set in the option parameter. 

[NO_FREE_DESC] 

The maximum number of simulated I/O files are already 
open. 

Return Value Upon successful completion, the file descriptor is returned. Otherwise, a 

value of -1 is returned and ermo is set to indicate the error. 

See Also close, lseek, read, write. 
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pos_cursor 



pos_cursor 



Position Cursor on Simulated I/O Display 



Synopsis 



# include < simio.h> 

int pos_cursor (int Hides, int col, int row); 



Description Pos_cursor positions the cursor to (column, line) on the display if stdout is 

directed to the display. 



Errors 



Pos_cursor will fail if one of the following conditions is true; errno will be set 
accordingly. 



[INVALID_CMD] 



Attempt to position the cursor on a file that is not a 
display. 



[INVALID_ROW_OR_COLUMN] 



Row is greater than or equal to 50 rows, or col is greater 
than or equal to 80 columns (or the number of columns 
on the display, whichever is greater). 



[INVALID_DESC] 

Fildes is not an open file descriptor. 

[CONTINUE_ERROR] 

Attempt to position the cursor after a continued 
emulation session (emulation is exited and then 
reentered). 



Return Value Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 

is returned and errno is set to indicate the error. 
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read 



read 



Read Input 



Synopsis # include < simio.h> 

int read (int Aides, void *buf, int nbyte); 



Description Read requests the host to read nbytes from the file specified by fildes and place 

them into buf. If the operation is successful, read returns the number of bytes 
read. If unsuccessful, read sets errno and returns -1. 

On devices capable of seeking, the read starts at a position in the file given by 
the file pointer associated with fildes. Upon return from read, the file pointer 
is incremented by the number of bytes actually read. 

Devices that are incapable of seeking always read from the current position. 
The value of a file pointer associated with such a device is undefined. 

Upon successful completion, read returns the number of bytes actually read 
and placed in the buffer; this number maybe less than nbyte if the number of 
bytes left in the file is less than nbyte bytes. A value of 0 is returned when an 
end-of-file has been reached. 



Errors Read will fail if one of the following conditions is true and errno will be set 

accordingly: 

[INVALID_DESC] 

Fildes is not a valid file descriptor open for reading. 

[INVALID_CMD] 

Attempt to read from the display. 
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read 



[CONTINUE_ERROR] 



[UNIX_ERROR] 



Attempt to read anything after a continued emulation 
session (emulation is exited and then reentered). 



Any error from host read(2). 



Return Value Upon successful completion a non-negative integer is returned indicating the 

number of bytes actually read. Otherwise, a -1 is returned and errno is set to 
indicate the error. 

Note 

Although no more than 255 bytes are transferred from the host at one time, 
there is no practical limit to the number of bytes that can be read per 
invocation of read. 



See Also open. 
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sbrk 



sbrk 



Get Block of Zero-Filled Memory from System Heap 



Synopsis 



# include < memory.h> 
void *sbrk (int increment); 



Description Sbrk is used to get a block of dynamically allocated memory, increment bytes in 

length, from the system heap. The newly allocated space is set to zero. 
Increment can be negative, in which case the amount of allocated space is 
decreased. 



Return Value Upon successful completion, sbrk returns a pointer to the first byte of the 

memory block requested. Otherwise, a value of -1 is returned. 



Warnings 



The pointer returned by sbrk is not aligned in any manner. Loading or storing 
words through this pointer could cause alignment problems. 

Care should be taken when using sbrk in conjunction with calls to the main 
memory allocator routines (malloc, calloc, realloc, and free). All these 
routines allocate and deallocate data memory from the system heap. Although 
you should not attempt this, it is possible to deallocate data memory allocated 
through the main memory allocator functions with a subsequent call to sbrk. 



See Also 



malloc, free, realloc, calloc, _getmem. 
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unlink 

Remove Directory Entry 

Synopsis # include < simio.h> 

int unlink (const char *path); 

Description Unlink causes the file whose name is pointed to by path to be removed; the file 

remains open, however, and can be accessed until it is closed. Subsequent 
attempts to open the file will fail, unless it is created anew. 



Errors Unlink will fail if one of the following conditions is true, and errno will be set 

accordingly. 

[INVALID_FILE_NAME] 



A component of the path prefix is not a directory. 
[FILE_NOT_FOUND] 

The named file does not exist, path is NULL, or a 
component of path does not exist. 

[NO_PERMISSION] 



Search permission is denied for a component of the 
path prefix. Write permission is denied for the 
directory containing the file to be removed. 

[UNIX_ERROR] 



The host unlink(2) function failed for some reason 
other than denied permissions. 
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Return Value Upon successful completion, a value of 0 is returned. Otherwise, a value of -1 

is returned and errno is set to indicate the error. 

See Also close, open. 
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write 

Write on a File 

Synopsis # include < simio.h> 

int write (int Aides, const void *buf, int nbyte); 

Description Write requests the host to write nbyte bytes from buflo the file specified by 

fildes. If the operation is successful, write returns the number of bytes written. 
If unsuccessful, write sets errno and returns -1. 

On devices capable of seeking, the actual writing of data proceeds from the 
position in the file indicated by the file pointer. Upon return from write, the 
file pointer is incremented by the number of bytes actually written. 

On devices incapable of seeking, writing always takes place starting at the 
device's current position. The value of a file pointer associated with such a 
device is undefined. 

If the 0_APPEND flag of the file status flags is set when the file is opened, the 
file pointer will be set to the end of the file prior to the first write. 

If a write requests that more bytes be written than there is room for, only as 
many bytes as there is room for will be written. For example, suppose there is 
space for 20 bytes more in a file before reaching a limit. A write of 512 bytes 
will return 20. The next write of a non-zero number of bytes will give a failure 
return (except as noted below). 
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Errors Write will fail and the file pointer will remain unchanged if one of the 

following conditions is true and errno will be set accordingly: 

[INVALID_DESC] 

Fildes is not a valid file descriptor open for writing. 

[UNIX_ERROR] 

The current file position (as set by Iseek) is less than 
zero. 

[INVALID_COMMAND] 

Fildes indicates the keyboard. 
[CONTINUE_ERROR] 

Attempt to write anything after a continued emulation 
session (emulation is exited and then reentered). 

Write will fail and the file pointer will be updated to reflect the amount of data 
transferred if one of the following conditions is true and errno will be set 
accordingly: 

[UNIX_ERROR] 

An attempt was made to write a file that exceeds the 
process's file size limit or the maximum file size. 

Return Value Upon successful completion, the number of bytes actually written is returned. 

Otherwise, -1 is returned, and errno is set to indicate the error. 

See Also lseek, open. 
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Compile-Time Errors 

Explanations of compile-time error messages. 
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Errors are problems which prevent a program from compiling successfully. 
When you see an error message, you must correct the error then compile the 
program again. 

Warnings are possible problems which may cause your program to execute 
incorrectly. When you see a warning message, you need to decide whether 
your code is correct. Warnings are listed at the end of this chapter. 

The errors and warnings are listed here in alphabetical order. 

In addition to the error or warning message, the compiler shows the line of 
code, the file name, and the line number. 



Errors 

Address initializer is too large to fit in declared type. This error can 

occur when an attempt is made to store a pointer in a variable which was 
declared with too small a size, such as "short" or "char." 

Address of automatic variable is not constant. 

Assign of ptr to const to ptr to non-const. This error occurs when a 
pointer to constant is assigned to a pointer to non-constant. For example: 

ptr_to_non_const = ptr_to_const ; 

This error prevents the inadvertent modification of constant data via pointers. 
A cast can be used to override this checking. 

Assign of ptr to volatile to ptr to non-volatile. This error occurs when a 
pointer to volatile is assigned to a pointer to non-volatile. 

ptr_to_non_volatile = ptr_to_volatile; 

This error prevents optimizations from being inadvertently made where the 
volatile type modifier has said that they shouldn't. A cast can be used to 
override this checking. 

Bad command line syntax. 
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Bad constant expression. This means that a non-constant expression has 
been used in a context where a constant expression is required. 

Bad digit in octal constant. 

Bad function declarator. This is a syntax error which occurs when the 
parser is expecting the start of a function definition. It is often followed by 
many errors due to the parser being out of sync. 

Bad integer constant. This error occurs when a non-integral constant is 
used in a context where an integer constant is required. 

Bit field < name> must be integral type. 

Bit width of < bit field name> cannot be 0. 

Bit width of < bit field name> too large. 

Break must be inside looping construct or switch. 

Can only initialize first member of a union. 

Can't access array member of non-lvalue structure. 

Can't declare void object < identifier/member name> . The only objects 

which maybe declared with type void are functions returning void and pointers 
to void. 

Cannot assign to a constant. This error occurs when a symbol declared 
with the "const" type modifier is assigned a value. 

Cannot have array Of functions. Arrays may not have functions as 
elements, but they may have pointers to functions as elements. {Hint: use 
typedef to declare a type "pointer to function," then declare an array of this 
type.) 

Cannot have array Of void. Although you cannot declare an array of void 
objects, you may declare an array of pointers to void. For example, you may 
declare void *ptr_array [10] . 
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Cannot take address Of a bit field. This error occurs when the unary 
address operator (&) is used on a bit field. 

Cannot take address Of a register. This error occurs when the unary 
address operator (&) is used on a variable declared with the register storage 
class specifier. 

Cannot take Sizeof this type. Sizeof cannot be applied to a function, bit 
field, a void, or an undimensioned array. 

Case statement must be inside switch. 
Case values must be integral. 

Character string constant exceeds maximum length. The maximum 
length for character strings is 1023 characters (1024 if the NULL is counted). 

Comment terminator '*/' without comment start. 

Condition Of '?:' must be scalar. The scalar types include the arithmetic 
types (char, short, int, long, float, double) and pointers. 

Constant literal too large. A constant literal has an implied type. If the 
value is too large for that type, then an error occurs. 

Continue must be inside looping construct. 

Control expression must be scalar. The scalar types include the 
arithmetic types (char, short, int, long, float, double) and pointers. 

Declaration for nonexistent parameter. This error occurs when a 
declaration list of formal parameters contains a declaration for a parameter 
not listed in the function declarator. 

Default statement must be inside switch. 

Division or modulo by zero. This error occurs when the compiler 
determines that a constant folding optimization will cause a divide by zero. 
Use the unary plus (+ ) operator to prevent the rearrangement of expressions. 

Duplicate label < identifier . 



268 



Chapter 9: Compile-Time Errors 



Duplicate structure or union member < name> . 
Empty character literal. 

Enum constant value not representable as int. All enumeration values 

must be representable in an int type. 

Exceeded automatic variable space. This error occurs when there is too 
much local storage. The limit is 2 6 -2 bytes. 

Exceeded parameter passing space. This error occurs when there is too 
much parameter storage. The limit is 2 16 -2 bytes. 

Expression too complex. 

Function call has fewer params than prototype. 

Function call has more params than prototype. 

Function cannot return array. 

Function cannot return function. 

Function parameter cannot be void. 

Goto non-existent label < identifier . 

Illegal cast operands. This error occurs when an expression cannot be 
converted to the type specified by the cast construct (for example, casting 
between a data pointer and a float). The cast operator can only be applied to 
scalar or void types 

Illegal Character in input. This is usually caused when a control character 
has been placed in the C source code. 

Illegal function name. 

Illegal operand types Of < operator> . The operand types are incompatible 
with the operator. 

Illegal preprocessor directive in input. 
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Incompatible array initializer. The initializer given for an array is not 
compatible with the type of the array elements. 

Incompatible initializer. The initializer given is not compatible with the type 
of the variable being initialized. 

Initializer too large for array. 
Interrupt routine must return type void. 

Left operand of < operator> must be an lvalue. An "lvalue" is an 

expression to which values can be assigned. 
Missing right delimiter on string literal. 
Mixed new and old style parameter declarations. 
More initializers than structure members. 
Multiple defaults in switch. 

Must init arithmetic type with arithmetic value. Arithmetic types (char, 

short, int, long, float, and double) must be initialized with arithmetic values. 

Must initialize bit field with integral constant. 

Must init pointer with compatible pointer or 0. A compatible pointer is a 
pointer with the same type or a data pointer with type (void *). (The NULL 
pointer constant is 0.) 

Near function < identifier called across segments. A call to a static 

function in a different segment has been attempted with the cc8086 "near calls" 
option specified. 

Negative or zero array size. 

No digits in hexadecimal constant. 

Only high order dimension of array can be empty. 

Operand of < operator> cannot be constant. 
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Operand of < operator> must be an lvalue. An "lvalue" is an expression 

to which values can be assigned. 

Operand Of < operator> must be arithmetic. The arithmetic types are: 
char, short, int, long, float, and double. 

Operand Of < operator> must be integral. The integral types are: char, 
short, int, and long. 

Operand of < operator> must be scalar. The scalar types include the 
arithmetic types (char, short, int, long, float, double) and pointers. 

Operand of pointer dereference must be a pointer. Something other 

than a pointer was found immediately following a dereferencing (indirection) 
operator *. Check the declaration of the operand to make sure it is a pointer. 
You may also see this error message if an arithmetic expression is incorrect 
(remember that ** is not an arithmetic operator in C). 

Operands of '[]' must be a pointer and an integral. This error occurs 
when the array name and the index are not alternately a pointer and an 
integral type (char, short, int, long). 

Operands Of < operator> must be integral. The integral types are: char, 
short, int, and long. 

Operands of < operator> must be scalar. The scalar types include the 

arithmetic types (char, short, int, long, float, double) and pointers. 

Overflow during floating point constant folding. This error occurs when 
the compiler determines that a constant folding optimization on floating-point 
values will cause an overflow. Use the unary plus (+ ) operator to prevent the 
rearrangement of expressions. 

Param expr type not compatible with prototype. 

Param list can only appear in definition. An old style declaration of a 
function so that another function may use it, like 

extern char foo (); 
cannot include parameters, as in 



271 



Chapter 9: Compile-Time Errors 



extern char foo (a, b) ; 

Only the function definition may include a parameter list. 

Param type of < name> differs from prototype. 
Parameter type must have id in function definition. 
Parameters not allowed for interrupt routine. 

Parser Stack overflow. This error occurs when the compiler has reached a 
syntactic translation limit. This will only occur in extreme cases. The 
translation limits are listed in the "C Compiler Overview" chapter. 

Redeclaration of section/segment for symbol < id> . 

This error occurs when the same symbol is declared in two differently named 
program segments. 

Redeclaration Of symbol < identifier . Rename one of the symbols. In 
some previous versions of the compiler technology, parameter names were 
ignored in prototype declarations. 

Redeclaration of tag < identifier . 

Redeclaration of whether symbol < identifier is ORGed. 

This error occurs when the same symbol is declared in a relocatable program 
segment and in an absolute program segment (defined with the SEGMENT 
pragma). 

Redefinition of function < identifier . 
Repeated case value. 

Return expression does not match function type. 

Reuse of absolute address for symbol < name> . This error occurs when 

absolute address segment declarations have been given such that address 
overlaps occur in the assembly code. All symbols located at a particular 
address must be in the same segment (prog, data, or const) and they must all 
be either defined in the same module or defined externally. 
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Static initializer not a representable constant. 

Structure can't contain function < member name> . If you want to store a 
function in a structure, store a pointer to the function. For example, int 
(*funcptr) () would be a valid structure element. 

Structure can't contain undimensioned array < identifier . You must 
give a dimension for any array inside a structure; for example, use i [10] 
instead of i [] . 

Structure can't contain void < member name> . Structure elements may 
not be objects of type void. However, pointers to void are allowed. For 
example void v is not allowed in a structure, but void *pv is allowed. 

Structure element reference of non-structure. The identifier in front of 
the "." was not declared as a structure. 

Switch condition must be integral. In sw±tch(expression) the expression 

must return a value of type int. 

Syntax error. This error is often caused by a missing semicolon on the 
preceding line. 

Type cannot have zero Size. This error will occur if the only member of a 
structure is a bit field whose size is zero. 

Type too large. This error occurs when a type's size is greater than 2 16 -2 
bytes. 

Undeclared structure member < name> . This error occurs when you 

attempt to access a structure member which has not been declared. 

Undeclared symbol < identifier . 

Underflow during floating point constant folding. This error occurs when 
the compiler determines that a constant folding optimization on floating-point 
values will cause an underflow. Use the unary plus (+ ) operator to prevent 
the rearrangement of expressions. 
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Uninitialized definition of undimensioned array. This error occurs when 

no dimension is specified in an array declaration. The highest order 
dimension in an array declaration may be empty if the declaration is initialized. 

Unknown or incorrect pragma (ignored). 

Unknown type Size. This error can occur when a variable declared with the 
type of an undeclared structure tag is used before the structure is declared. 

Unresolved static function < name> . This error indicates that a static 
function of the form "static f();" was declared, but the function body was never 
defined. 



Warnings 

Alias symbol < name> already referenced. Place the # pragma ALIAS 

before the symbol is used. For example, place it immediately before or after 
the declaration. The alias will not cause substitution of the symbol name in 
any references which precede the alias. 

Array index out of range. 

Assignment between different pointer types. 

Assignment between pointer and integer. 

Cast from less to more restrictive pointer. This warning message is 
enabled when the cc8086 "generate additional warnings" option is specified. 

Comparison between different pointer types. 
Comparison between pointer and integer. 

Confusing line directives may affect debug info. This warning indicates 

that the line synchronization information passed to the compiler did not 
correspond to a proper nesting of include files. This is probably due to 
inconsistent # line directives in the source. 
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Duplicate const qualifier on type. The type was already declared as const. 

Duplicate volatile qualifier on type. The type was already declared as 
volatile. 

Empty body Of control Statement. This warning message is enabled when 
the cc8086 "generate additional warnings" option is specified. 

Empty external declaration. 

Extern < identifier assumed to be in UDATA. The compiler cannot 
determine if the external identifier was initialized and has placed the identifier 
in the UDATA segment. If the variable is initialized, it is very important to 
place the variable in the correct segment (idata). To do this, use a # pragma 
SEGMENT DATA= idata before the external declaration to name the 
initialized data segment. See the "Embedded Systems" chapter for more 
information. (This condition occurs only when the "separate initialized and 
uninitialized data" option is used). 

External symbol < identifier exceeds significant length. 

Illegal escaped character. Backslash ignored. As an example, the string 

"\q" would cause the warning to be generated, and the string would become "q". 

Local variable < identifier referenced only once. 

Missing parameter declaration (defaulted to int). This warning message 

is enabled when the cc8086 "generate additional warnings" option is specified. 

Mixing extern declaration of < identifier with near calls. This warning 
message is enabled when the cc8086 "NEAR calls" compiler option is specified 
and a function is declared as extern and later as static. The resulting symbol is 
changed from extern to static in midstream, which may result in incorrect 
"NEAR" calls to a "FAR" function. Remember that the extern declaration may 
be implicit. 

Mixing function pointer < identifier with near calls. 

This warning message is enabled when the cc8086 "near calls" option is 
specified and function pointers are declared. 

More than one character in character literal. 
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No emulation local syms if .c and .A file not in same directory. This 
warning is generated whenever a path to a source file is specified and the 
"generate HP 64000 format files" option is used. If you will be using an 
emulator, compile all sources in the directory where they exist. 

Non-constant initializer for constant type variable. 
Octal or hex character constant too big (truncated). 
Shift by out of range constant value. 

Static initializer Will not be loaded. This warning is enabled when the 
"uninitialized data" compiler command line option is specified. It warns that 
there is no load-time initialization for statics and externals 

Struct, union, or enum tag used but not declared. It is possible to 

declare pointers to structures or unions before they are defined. The C 
language allows this form of forward referencing. This message means that a 
forward reference for a tag was seen, but never resolved. This warning message 
is enabled when the cc8086 "generate additional warnings" option is specified. 

Test expression is an assignment. This warning message is enabled when 
the cc8086 "generate additional warnings" option is specified. 

Unreferenced symbol < identifier . The symbol was declared but is not 
used. 
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Run-Time Errors 

Explanations of run-time error messages. 
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There are three basic types of run-time error messages. The largest group is 
generated by floating-point exceptions. The two smaller groups are debug 
error messages and startup error messages. 



Floating-Point Error Messages 

In accordance with the IEEE floating-point standard, trapping on 
floating-point exceptions maybe enabled or disabled. (See the _fp_error 
description in the "Libraries" chapter.) If the trap associated with a specific 
exception is disabled, an IEEE defined value is returned, a global exception 
flag is set, and no error message is displayed. Conversely, if the trap is enabled 
and an exception is detected, an error message is displayed on the emulation 
status line and the program terminates. This type of error message is 
composed as follows: 
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Fit Pt Invalid Operation. This error occurs when an operand is invalid for 
the operation performed. Examples include: 

• 0 * Infinity. 

• (+ Infinity) + (-Infinity). 

• 0/0 or Infinity/Infinity. 

• Comparison between NaN and any other value. 

• Floating point register variable is read without having been initialized 
(8087 only). 

Fit Pt Overflow. This error occurs when the result of an operation is too 
large to be represented in the destination format. 

Fit Pt Underflow. This error occurs when the result of an operation is too 
small to be represented in the destination format. If trapping is disabled, the 
result will be denormalized. 

Fit Pt Divide by Zero. This error occurs when attempting to divide a 
non-zero value by zero. (Zero divided by zero is an invalid operation error.) 

Fit Pt Imprecise. This error occurs when the result requires rounding. Due 
to the high probability of rounding, this trap is typically disabled. 

Fit Pt Significance LOSS. This error occurs when precision is lost during the 
reduction of large arguments in the trigonometric functions. 

Fit Pt Denormal This error occurs after an operation is attempted on a 
denormal number (8087 only). 



Debug Error Messages 

If programs are compiled using the "generate run-time error checking" option, 
code is generated to perform checks for the dereferencing of NULL and 
uninitialized pointers, and for range errors in array accesses. If one of these 
conditions occurs, the following type of message is displayed: 
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Pointer Faults: 



<file>:<line number> nil ptr 
<file>:<line number> uninit ptr 

Range Faults: 

<file> : <line number> <index> > <max index> 
<file>:<line number> <index> < 0 

Where < file> refers to the C source file containing the offending instruction. 
This field maybe truncated, if necessary, to 12 characters after the ".c" 
extension is removed from the file name. 

Where < line number> is the line number within the C source file which 
contains the offending instruction. 

Where < index> is the index into the array. 

And where <max index> is the upper bound of the array. This field maybe 
replaced with "max" if the message won't fit on the status line. 
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Startup Error Messages 

If the crtO program setup file is linked with the program, the startup routine is 
called to open the, stdin, stdout, and stderr streams. If for any reason one of 
these files cannot be opened, the following type of message is displayed: 

Can't open <file>, prog aborted 

Where <file> is either "stdin", "stdout", or "stderr". 

At program termination, a message is always displayed. This message is 
composed within the _exit_msg() library routine and is: 

Program end, returned <arg> 

Where < arg> is either the value returned by main() or the argument passed 
to an explicit call to exit(). 

If an integer divide by zero is attempted, the program will terminate with the 
following message displayed: 

Integer divide by zero 
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Run-Time Routines 

Descriptions of run-time routines. 
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Run-time library routines are usually called by compiler generated code; 
however, they maybe called from assembly language programs as well 
(including embedded assembly code within the C source file). The routines 
listed here may in turn call other subroutines; those subroutines are not listed 
here. 



Note These run-time routines may change in future versions of the compiler. 

The names of some run-time routines have changed between versions of the 
compiler; for example, many large model routines were renamed from _L to 
_LM when support for the medium memory model was added. 



The following conventions are followed for this appendix: 



< size> _S or JSC for the small memory model, _L or _LM for 

the large memory model, _C or JSC for the compact 
memory model, _M or _LM for the medium model. 

< pointer size> 16 for the small memory model, 32 for the large 

memory model. 

DXAX 32-bit pseudo-register consisting of registers DX and 

AX with DX holding the most significant word. 

ESDI 32-bit pseudo-register consisting of registers ES and DI 

with ES holding the segment and DI holding the offset. 

F64 Double (8 bytes). 

F32 Float (4 bytes). 

UI32 Unsigned Long (4 bytes). 

132 Signed Long (4 bytes) . 

UI16 Unsigned Integer (2 bytes). 

116 Signed Integer (2 bytes). 
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() Indirection. For example, (DI) represents the memory 

location pointed to by register DI. 

PARMO Last parameter pushed on the stack. 

PARM1 If present, this parameter is pushed on the stack just 

prior to PARMO. These parameters maybe four or 
eight bytes in size, depending on the specific library 
routine. Some routines do not use the stack to pass 
parameters. 

Figures 9-1 through 9-4 can be found at the end of this appendix. 
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Conversion Routines 



F64_TO_F32< size> 

Converts a 64-bit floating point value to a 32-bit floating point value by 
rounding to nearest. A zero is returned for a denormal 64-bit floating point 
value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 

F32 TO F64< size> 



F64in PARM0(8bytes). 
F32 in register DXAX. 
BX,CX. 

PARMO is deallocated by this routine via RET 8. 
DXAX <-cast PARMO. 
Figure 9-1. 



Converts a 32-bit floating point value to a 64-bit floating point value. A zero is 
returned for a denormal 32-bit floating point value. The additional mantissa 
bits of the 64-bit floating point value are always returned zero, even when 
converting an NaN. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



F32 in register DXAX. 
F64in PARMO (8 bytes). 
BX,CX,DI. 
None. 

PARMO <-cast DXAX. 
Figure 9-1. 
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Conversion Routines 



F64 TO UI32< size> 



Converts a 64-bit floating point value to a 32-bit unsigned integer by 
truncation. Floating point values that cannot be represented by a 32-bit 
unsigned integer return 0x80000000. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



F64in PARM0(8bytes). 
UI32 in register DXAX. 
BX, CX, DI. 

PARM0 is deallocated by this routine via RET 8. 
DXAX <-cast PARM0. 
Figure 9-1. 



UI32_TO_F64< size> 

Converts a 32-bit unsigned integer to a 64-bit floating point value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



UI32 in register DXAX. 
F64in PARM0(8bytes). 
AX, BX, CX, DX, DI. 
None. 

PARM0 <-cast DXAX. 
Figure 9-1. 
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Conversion Routines 



F64_TO_UI16< size> 

Converts a 64-bit floating point value to a 16-bit unsigned integer by 
truncation. Floating point values that cannot be represented by a 16-bit 
unsigned integer return 0x8000. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



F64in PARM0(8bytes). 
UI16 in register AX. 
BX,CX,DX,DI. 

PARMO is deallocated by this routine via RET 
AX <-cast PARMO. 
Figure 9-1. 



UI16_TO_F64< size> 

Converts a 16-bit unsigned integer to a 64-bit floatingpoint value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



UI16 in register AX. 
F64in PARMO (8 bytes). 
AX, BX, CX, DX, DI. 
None. 

PARMO <-cast AX. 
Figure 9-1. 
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Conversion Routines 



F64 TO I32< size> 



Converts a 64-bit floatingpoint value to a 32-bit signed integer by truncation. 
Floating point values that cannot be represented by a 32-bit signed integer 
return 0x80000000. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



F64in PARM0(8bytes). 
132 in register DXAX. 
BX, CX, DI. 

PARM0 is deallocated by this routine via RET 8. 
DXAX <-cast PARM0. 
Figure 9-1. 



I32_T0_F64< size> 

Converts a 32-bit signed integer to a 64-bit floating point value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



132 in register DXAX. 
F64in PARM0(8bytes). 
AX, BX, CX, DX, DI. 
None. 

PARM0 <-cast DXAX. 
Figure 9-1. 
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Conversion Routines 



F64_T0_I16< size> 

Converts a 64-bit floatingpoint value to a 16-bit signed integer by truncation. 
Floating point values that cannot be represented by a 16-bit signed integer 
return 0x8000. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



F64in PARM0(8bytes). 
116 in register AX. 
BX,CX,DX,DI. 

PARMO is deallocated by this routine via RET 8. 
AX <-cast PARMO. 
Figure 9-1. 



11 6_TO_F64 <size> 

Converts a 16-bit signed integer to a 64-bit floatingpoint value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



116 in register AX. 
F64in PARMO (8 bytes). 
AX, BX, CX, DX, DI. 
None. 

PARMO <-cast AX. 
Figure 9-1. 



290 



Chapter 1 1 : Run-Time Routines 

Conversion Routines 



F32 TO UI32< size> 



Converts a 32-bit floating point value to a 32-bit unsigned integer by 
truncation. Floating point values that cannot be represented by a 32-bit 
unsigned integer return 0x80000000. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



F32 in register DXAX. 
UI32 in register DXAX. 
BX, CX, DI. 
None. 

DXAX <-cast DXAX. 



UI32_TO_F32< size> 

Converts a 32-bit unsigned integer to a 32-bit floatingpoint value by rounding 
to nearest. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



UI32 in register DXAX. 
F32 in register DXAX. 
BX, CX, DI. 
None. 

DXAX <-cast DXAX. 
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Conversion Routines 



F32_TO_UI16< size> 

Converts a 32-bit floatingpoint value to a 16-bit unsigned integer by 
truncation. Floatingpoint values that cannot be represented by a 16-bit 
unsigned integer return 0x8000. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



F32 in register DXAX. 
UI16 in register AX. 
CX,DX. 
None. 

AX <-cast DXAX. 



UI16_TO_F32< size> 

Converts a 16-bit unsigned integer to a 32-bit floatingpoint value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



UI16 in register AX. 
F32 in register DXAX. 
None. 
None. 

DXAX <-cast AX. 
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Chapter 1 1 : Run-Time Routines 

Conversion Routines 



F32 TO I32< size> 



Converts a 32-bit floatingpoint value to a 32-bit signed integer by truncation. 
Floating point values that cannot be represented by a 32-bit signed integer 
return 0x80000000. 



F32 in register DXAX. 
132 in register DXAX. 
BX, CX, DI. 
None. 

DXAX <-cast DXAX. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

132 TO F32< size> 



Converts a 32-bit signed integer to a 32-bit floating point value byrounding to 
nearest. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



132 in register DXAX. 
F32 in register DXAX. 
BX, CX, DI. 
None. 

DXAX <-cast DXAX. 
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Chapter 1 1 : Run-Time Routines 

Conversion Routines 



F32_T0_I16< size> 

Converts a 32-bit floatingpoint value to a 16-bit signed integer by truncation. 
Floating point values that cannot be represented by a 16-bit signed integer 
return 0x8000. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



F32 in register DXAX. 
116 in register AX. 
CX, DX. 
None. 

AX <-cast DXAX. 



H 6_TO_F32 <size> 

Converts a 16-bit signed integer to a 32-bit floatingpoint value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



116 in register AX. 
F32 in register DXAX. 
None. 
None. 

DXAX <-cast AX. 
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Floating Point Addition Routines 



ADD_F64A< size> 

Adds two 64-bit floating point values, returning a 64-bit floating point value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



F64 addend in PARM1 (8 bytes). 
F64 addor in PARMO (8 bytes). 

F64 result in PARM1 (8 bytes). 

AX,BX,CX,DX,DI. 

PARMO is deallocated by this routine via RET 8. 
PARM1 <-PARMl + PARMO. 
Figure 9-2. 
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Floating Point Addition Routines 

ADD_F64B<s/ze> 

Adds two 64-bit floating point values, returning a 64-bit floating point value in 
two places. 

Input: Pointer to F64 addend/result in DI. 

F64 addor in PARMO (8 bytes). 

Output: F64 result in memory location pointed to by DI. 

F64 result in PARMO (8 bytes). 

Registers Destroyed: AX, BX, CX, DX. 

Side Effects: None. 

Synopsis: (DI),PARM0 <-(DI) + PARMO. 

Stack Upon Entry: Figure 9-1. 

ADD_F64C<s/ze> 

Adds two 64-bit floating point values, returning a 64-bit floating point value. 

Input: Pointer to F64 addend/result in DI. 

F64 addor in PARMO (8 bytes). 

Output: F64 result in memory location pointed to by DI. 

Registers Destroyed: AX, BX, CX, DX. 

Side Effects: PARMO is deallocated by this routine via RET 8. 

Synopsis: (DI) <-(DI) + PARMO. 

Stack Upon Entry: Figure 9-1. 
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Chapter 1 1 : Run-Time Routines 

Floating Point Addition Routines 



INC F64< size> 



Adds 1.0 to a 64-bit floating point value, returning two 64-bit floating point 
values; the original value and the incremented value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



Pointer to F64 source/result operand in DI. 

Original F64 source value (pointed to by DI) in 
PARM0(8bytes). 

F64 result in memory location pointed to by DI. 

AX, BX, CX, DX. 

None. 

PARM0<-(DI). 
(DI)<-(DI)+ 1.0. 

Figure 9-1. 



ADD_F32A< size> 

Adds two 32-bit floating point values, returning a 32-bit floating point value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



F32 addend in PARM1 (4 bytes). 
F32 addor in PARMO (4 bytes). 

F32 result in PARM1 (4 bytes). 

AX, BX, CX, DX, DI. 

PARMO is deallocated by this routine via RET 4. 
PARM1 <-PARMl + PARMO. 
Figure 9-4. 
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Floating Point Addition Routines 

ADD_F32B< size> 

Adds two 32-bit floating point values, returning a 32-bit floating point value in 
two places. 

Input: Pointer to F32 addend/result in DI. 

F32 addor in PARMO (4 bytes). 

Output: F32 result in memory location pointed to by DI. 

F32 result in PARMO (4 bytes). 

Registers Destroyed: AX, BX, CX, DX. 

Side Effects: None. 

Synopsis: (DI),PARM0 <-(DI) + PARMO. 

Stack Upon Entry: Figure 9-3. 

ADD_F32C<s/ze> 

Adds two 32-bit floating point values, returning a 32-bit floating point value. 

Input: Pointer to F32 addend/result in DI. 

F32 addor in PARMO (4 bytes). 

Output: F32 result in memory location pointed to by DI. 

Registers Destroyed: AX, BX, CX, DX. 

Side Effects: PARMO is deallocated by this routine via RET 4. 

Synopsis: (DI) <-(DI) + PARMO. 

Stack Upon Entry: Figure 9-3. 
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Chapter 1 1 : Run-Time Routines 

Floating Point Addition Routines 



INC F32< size> 



Adds 1 .0 to a 32-bit floating point value, returning two 32-bit floating point 
values: the original value; the incremented value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 



Pointer to F32 source/result operand in DI. 

Original F32 source value (pointed to by DI) in 
PARM0(4bytes). 

F32 result in memory location pointed to by DI. 

AX, BX, CX, DX. 

None. 



Synopsis: PARMO <-(DI). 

(DI)<-(DI)+ 1.0. 

Stack Upon Entry: Figure 9-3. 
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Floating Point Subtraction Routines 



SUB_F64A< size> 

Subtracts a 64-bit floating point value from another 64-bit floating point 
value, returning a 64-bit floating point value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 

SUB F64B< size> 



F64 minuend in PARM1 (8 bytes). 
F64 subtrahend in PARMO (8 bytes). 

F64 result in PARM1 (8 bytes). 

AX,BX,CX,DX,DI. 

PARMO is deallocated by this routine via RET 
PARM1 <-PARMl - PARMO. 
Figure 9-2. 



Subtracts a 64-bit floating point value from another 64-bit floating point 
value, returning a 64-bit floating point value in two places. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



Ptr to F64 minuend/result in DI. 
F64 subtrahend in PARMO (8 bytes). 

F64 result in memory location pointed to by DI. 
F64 result in PARMO (8 bytes). 

AX,BX,CX,DX. 

None. 

(DI),PARM0 <-(DI) - PARMO. 
Figure 9-1. 
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Chapter 1 1 : Run-Time Routines 

Floating Point Subtraction Routines 



SUB F64C< size> 



Subtracts a 64-bit floating point value from another 64-bit floating point 
value, returning a 64-bit floating point value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 

DEC F64< size> 



Pointer to F64 minuend/result in DI. 
F64 subtrahend in PARMO (8 bytes). 

F64 result in memory location pointed to by DI. 

AX, BX, CX, DX. 

PARMO is deallocated by this routine via RET 8. 
(DI) <-(DI)- PARMO. 
Figure 9-1. 



Subtracts 1.0 from a 64-bit floating point value, returning two 64-bit floating 
point values; the original value and the decremented value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



Pointer to F64 source/result operand in DI. 

Original F64 source value (pointed to by DI) in 
PARMO (8 bytes). 

F64 result in memory location pointed to by DI. 

AX, BX, CX, DX. 

None. 

PARMO <-(DI). 
(DI)^(DI)-1.0. 



Stack Upon Entry: 



Figure 9-1. 
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Floating Point Subtraction Routines 



SUB_F32A< size> 

Subtracts a 32-bit floating point value from another 32-bit floating point 
value, returning a 32-bit floating point value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 

SUB F32B< size> 



F32 minuend in PARM1 (4 bytes). 
F32 subtrahend in PARMO (4 bytes). 

F32 result in PARM1 (4 bytes). 

AX,BX,CX,DX,DI. 

PARMO is deallocated by this routine via RET 4. 
PARM1 <-PARMl - PARMO. 
Figure 9-4. 



Subtracts a 32-bit floating point value from another 32-bit floating point 
value, returning a 32-bit floating point value in two places. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



Pointer to F32 minuend/result in DI. 
F32 subtrahend in PARMO (4 bytes). 

F32 result in memory location pointed to by DI. 
F32 result in PARMO (4 bytes). 

AX, BX, CX, DX. 

None. 

(DI),PARM0 <-(DI) - PARMO. 
Figure 9-3. 
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Chapter 1 1 : Run-Time Routines 

Floating Point Subtraction Routines 



SUB F32C< size> 



Subtracts a 32-bit floating point value from another 32-bit floating point 
value, returning a 32-bit floating point value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 

DEC F32< size> 



Pointer to F32 minuend/result in DI. 
F32 subtrahend in PARMO (4 bytes). 

F32 result in memory location pointed to by DI. 

AX, BX, CX, DX. 

PARMO is deallocated by this routine via RET 4. 
(DI) <-(DI)- PARMO. 
Figure 9-3. 



Subtracts 1.0 from a 32-bit floating point value, returning two 32-bit floating 
point values; the original value and the decremented value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



Pointer to F32 source/result operand in DI. 

Original F32 source value (pointed to by DI) in 
PARMO (4 bytes). 

F32 result in memory location pointed to by DI. 

AX, BX, CX, DX. 

None. 

PARMO <-(DI). 
(DI)^(DI)-1.0. 



Stack Upon Entry: 



Figure 9-3. 



303 



Chapter 1 1 : Run-Time Routines 

Floating Point Multiplication Routines 



Floating Point Multiplication Routines 



MUL_F64A< size> 

Multiplies two 64-bit floating point values, returning a 64-bit floating point 
value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 

MUL F64B< size> 



F64 multiplicand in PARM1 (8 bytes). 
F64 multiplier in PARMO (8 bytes). 

F64 result in PARM1 (8 bytes). 

AX,BX,CX,DX,DI. 

PARMO is deallocated by this routine via RET 8. 
PARM1 <-PARMl *PARM0. 
Figure 9-2. 



Multiplies two 64-bit floating point values, returning a 64-bit floating point 
value in two places. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



Pointer to F64 multiplicand/result in DI. 
F64 multiplier in PARMO (8 bytes). 

F64 result in memory location pointed to by DI. 
F64 result in PARMO (8 bytes). 

AX,BX,CX,DX. 

None. 

(DI),PARM0 <-(DI) *PARM0. 
Figure 9-1. 
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Chapter 1 1 : Run-Time Routines 

Floating Point Multiplication Routines 



MUL F64C< size> 



Multiplies two 64-bit floating point values, returning a 64-bit floating point 
value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 

MUL F32A< size> 



Pointer to F64 multiplicand/result in DI. 
F64 multiplier in PARMO (8 bytes). 

F64 result in memory location pointed to by DI. 

AX, BX, CX, DX. 

PARMO is deallocated by this routine via RET 8. 
(DI) <-(DI) *PARM0. 
Figure 9-1. 



Multiplies two 32-bit floating point values, returning a 32-bit floating point 
value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



F32 multiplicand in PARM1 (4 bytes). 
F32 multiplier in PARMO (4 bytes). 

F32 result in PARM1 (4 bytes). 

AX, BX, CX, DX, DI. 

PARMO is deallocated by this routine via RET 4. 
PARM1 <-PARMl *PARM0. 
Figure 9-4. 
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Chapter 1 1 : Run-Time Routines 

Floating Point Multiplication Routines 

MUL F32B< size> 



Multiplies two 32-bit floating point values, returning a 32-bit floating point 
value in two places. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 

MUL F32C< size> 



Pointer to F32 multiplicand/result in DI. 
F32 multiplier in PARMO (4 bytes). 

F32 result in memory location pointed to by DI. 
F32 result in PARMO (4 bytes). 

AX,BX,CX,DX. 

None. 

(DI),PARM0 <-(DI) *PARM0. 
Figure 9-3. 



Multiplies two 32-bit floating point values, returning a 32-bit floating point 
value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



Pointer to F32 multiplicand/result in DI. 
F32 multiplier in PARMO (4 bytes). 

F32 result in memory location pointed to by DI. 

AX, BX, CX, DX. 

PARMO is deallocated by this routine via RET 4. 
(DI) <-(DI) *PARM0. 
Figure 9-3. 
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Floating Point Division Routines 



DIV_F64A< size> 

Divides a 64-bit floating point value by another 64-bit floating point value, 
returning a 64-bit floating point value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 

DIV F64B< size> 



F64 dividend in PARM1 (8 bytes). 
F64 divisor in PARMO (8 bytes). 

F64 result in PARM1 (8 bytes). 

AX,BX,CX,DX,DI. 

PARMO is deallocated by this routine via RET 
PARM1 <-PARMl / PARMO. 
Figure 9-2. 



Divides a 64-bit floating point value by another 64-bit floating point value, 
returning a 64-bit floating point value in two places. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



Pointer to F64 dividend/result in DI. 
F64 divisor in PARMO (8 bytes). 

F64 result in memory location pointed to by DI. 
F64 result in PARMO (8 bytes). 

AX,BX,CX,DX. 

None. 

(DI),PARM0 <-(DI) / PARMO. 
Figure 9-1. 
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Floating Point Division Routines 



DIV_F64C< size> 

Divides a 64-bit floating point value by another 64-bit floating point value, 
returning a 64-bit floating point value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 

DIV F32A< size> 



Pointer to F64 dividend/result in DI. 
F64 divisor in PARMO (8 bytes). 

F64 result in memory location pointed to by DI. 

AX, BX, CX, DX. 

PARMO is deallocated by this routine via RET 8 
(DI)<-(DI) /PARMO. 
Figure 9-1. 



Divides a 32-bit floating point value by another 32-bit floating point value, 
returning a 32-bit floating point value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



F32 dividend in PARM1 (4 bytes). 
F32 divisor in PARMO (4 bytes). 

F32 result in PARM1 (4 bytes). 

AX, BX, CX, DX, DI. 

PARMO is deallocated by this routine via RET 4. 
PARM1 <-PARMl / PARMO. 
Figure 9-4. 
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Floating Point Division Routines 



DIV F32B< size> 



Divides a 32-bit floating point value by another 32-bit floating point value, 
returning a 32-bit floating point value in two places. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 

DIV F32C< size> 



Pointer to F32 dividend/result in DI. 
F32 divisor in PARMO (4 bytes). 

F32 result in memory location pointed to by DI. 
F32 result in PARMO (4 bytes). 

AX,BX,CX,DX. 

None. 

(DI),PARM0 <-(DI) / PARMO. 
Figure 9-3. 



Divides a 32-bit floating point value by another 32-bit floating point value, 
returning a 32-bit floating point value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

Stack Upon Entry: 



Pointer to F32 dividend/result in DI. 
F32 divisor in PARMO (4 bytes). 

F32 result in memory location pointed to by DI. 

AX, BX, CX, DX. 

PARMO is deallocated by this routine via RET 4. 
(DI) <-(DI) /PARMO. 
Figure 9-3. 
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Floating Point Comparison Routines 



EQUAL_F64< size> 

Compares two 64-bit floating point values, returning a 16-bit value of 0 if 
operandi * operand2, and 1 if operandi = operand2. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 

Synopsis: 

Stack Upon Entry: 



F64 operandi in PARM1 (8 bytes). 
F64 operand2 in PARMO (8 bytes). 

Boolean in AX where 0 = false, 
1 = true. 

CX,DX,DI. 

PARMO and PARM1 are deallocated by this 
routine via RET 16. 

AX <- 1 if { PARM 1 = PARMO } is true, 
0 otherwise. 

Figure 9-2. 
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Floating Point Comparison Routines 



EQUAL F32< size> 



Compares two 32-bit floating point values, returning a 16-bit value of 0 if 
operandi * operand2, and 1 if operandi = operand2. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



F32 operandi in register DXAX. 
F32 operand2 in register CXBX. 

Boolean in AX where 0 = false, 
1 = true. 

BX,CX,DX,DI. 

None. 

AX <- 1 if { DXAX = CXBX } is true, 0 otherwise. 



LESS_F64< size> 

Compares two 64-bit floating point values, returning a 16-bit value of 0 if 
operandi > operand2, and 1 if operandi < operand2. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 

Synopsis: 

Stack Upon Entry: 



F64 operandi in PARM1 (8 bytes). 
F64 operand2 in PARMO (8 bytes). 

Boolean in AX where 0 = false, 
1 = true. 

CX, DX, DI. 

PARMO and PARM1 are deallocated by this 
routine via RET 16. 

AX<-1 if {PARM1 < PARMO} is true, 
0 otherwise. 

Figure 9-2. 
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Floating Point Comparison Routines 

LESS F32< size> 



Compares two 32-bit floating point values, returning a 16-bit value of 0 if 
operandi > operand2, and 1 if operandi < operand2. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



F32 operandi in register DXAX. 
F32 operand2 in register CXBX. 

Boolean in AX where 0 = false, 
1 = true. 

BX,CX,DX,DI. 

None. 

AX <— 1 if {DXAX < CXBX} is true, 0 otherwise. 



LESS_EQ_F64< size> 

Compares two 64-bit floating point values, returning a 16-bit value of 0 if 
operandi > operand2, and 1 if operandi < operand2. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 

Synopsis: 

Stack Upon Entry: 



F64 operandi in PARM1 (8 bytes). 
F64 operand2 in PARMO (8 bytes). 

Boolean in AX where 0 = false, 
1 = true. 

CX, DX, DI. 

PARMO and PARM1 are deallocated by this 
routine via RET 16. 

AX<-lif{PARMl< PARMO} is true, 
0 otherwise. 

Figure 9-2. 
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Floating Point Comparison Routines 

LESS_EQ_F32< size> 

Compares two 32-bit floating point values, returning a 16-bit value of 0 if 
operandi > operand2, and 1 if operandi < operand2. 

Input: F32 operandi in register DXAX. 

F32 operand2 in register CXBX. 

Output: Boolean in AX where 0 = false, 

1 = true. 

Registers Destroyed: BX, CX, DX, DI. 
Side Effects: None. 

Synopsis: AX <-l if {DXAX < CXBX} is true, 0 otherwise. 
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Integer Multiplication Routines 



MUL_I32A< size> 

Multiplies two 32-bit long values (signed or unsigned), returning a 32-bit long 
value (signed or unsigned as appropriate). 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

MUL I32B< size> 



132 or UI32 multiplicand in register CXDI. 
132 or UI32 multiplier in register AXBX. 

132 or UI32 result in register DXAX. 

CX. 

None. 

DXAX^-CXDI *AXBX 



Multiplies two 32-bit long values (signed or unsigned), returning a 32-bit long 
value (signed or unsigned as appropriate) in two places. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



Pointer to 132 or UI32 multiplicand/result in DI. 
132 or UI32 multiplier in register AXBX. 

132 or UI32 result in memory location pointed to by 
DI. 

132 or UI32 result in register DXAX. 

CX. 

None. 

(DI),DXAX <-(DI) * AXBX. 
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Integer Division Routines 



DIV_UI32A< size> 

Divides a 32-bit unsigned long value by another 32-bit unsigned long value, 
returning a 32-bit unsigned long value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



UI32 dividend in register CXDI. 
UI32 divisor in register AXBX. 

UI32 result in register DXAX. 

BX, DI. 

None. 

DXAX <-CXDI / AXBX. 



DIV_UI32B< size> 

Divides a 32-bit unsigned long value by another 32-bit unsigned long value, 
returning a 32-bit unsigned long value in two places. 

Input: Pointer to UI32 dividend/result in DI. 

UI32 divisor in register AXBX. 

Output: UI32 result in memory location pointed to by DI. 

UI32 result in register DXAX. 

Registers Destroyed: BX, CX. 

Side Effects: None. 

Synopsis: (DI),DXAX <-(DI) / AXBX. 
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Integer Division Routines 



DIV I32A< size> 



Divides a 32-bit signed long value by another 32-bit signed long value, 
returning a 32-bit signed long value. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



132 dividend in register CXDI. 
132 divisor in register AXBX. 

132 result in register DXAX. 

BX,CX,DI. 

None. 

DXAX <-CXDI / AXBX. 



DIV_I32B< size> 

Divides a 32-bit signed long value by another 32-bit signed long value, 
returning a 32-bit signed long value in two places. 

Input: Pointer to 132 dividend/result in DI. 

132 divisor in register AXBX. 

Output: 132 result in memory location pointed to by DI. 

132 result in register DXAX. 

Registers Destroyed: BX, CX. 

Side Effects: None. 

Synopsis: (DI),DXAX <-(DI) / AXBX. 
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Integer Modulo Routines 



MOD_UI32A< size> 

Divides a 32-bit unsigned long value by another 32-bit unsigned long value, 
returning a 32-bit unsigned long remainder. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 

MOD UI32B< size> 



UI32 dividend in register CXDI. 
UI32 divisor in register AXBX. 

UI32 result in register DXAX. 

CX,DI. 

None. 

DXAX <-CXDI mod AXBX. 



Divides a 32-bit unsigned long value by another 32-bit unsigned long value, 
returning a 32-bit unsigned long remainder in two places. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



Pointer to UI32 dividend/result in DI. 
UI32 divisor in register AXBX. 

UI32 result in memory location pointed to by DI. 
UI32 result in register DXAX. 

CX. 

None. 

(DI),DXAX <-(DI) mod AXBX. 
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Integer Modulo Routines 



MOD I32A< size> 



Divides a 32-bit signed long value by another 32-bit signed long value, 
returning a 32-bit signed long remainder. 



Input: 
Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



132 dividend in register CXDI. 
132 divisor in register AXBX. 

132 result in register DXAX. 

CX,DI. 

None. 

DXAX <-CXDI mod AXBX. 



M0D_I32B< size> 

Divides a 32-bit signed long value by another 32-bit signed long value, 
returning a 32-bit signed long remainder in two places. 

Input: Pointer to 132 dividend/result in DI. 

132 divisor in register AXBX. 

Output: 132 result in memory location pointed to by DI. 

132 result in register DXAX. 

Registers Destroyed: CX. 

Side Effects: None. 

Synopsis: (DI),DXAX <-(DI) mod AXBX. 
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Pointer and Range Fault Routines 
FAULT PTR< size> 

Traps the appropriate error when a pointer is checked and found to be 
uninitialized or containing a NIL. A call to _error_msg(fault_type, text _ptr, 
line_num ) is made with fault_type set to 0 for a NIL pointer and -1 for an 
unitialized pointer, text jptr points to the filename and line_num is the line 
number. 

Input: Fault code number in register AX where: 

0 = NIL pointer 
-1 = Uninitialized pointer 

< pointer size> -bit pointer at TOS to information 
block of the form: 
UI32 line number 

Filename (variable number of bytes) 
0 (Filename terminator) 

Output: None. 

Registers Destroyed: N/A 

Side Effects: This routine may not be returned from. 

Synopsis: Call _error_msg(fault_type, text _ptr, line_num) and 

never return. 



319 



Chapter 1 1 : Run-Time Routines 

Pointer and Range Fault Routines 



FAULT UI32< size> 



Traps the appropriate error when an unsigned long variable is checked and 
found to be outside of a predefined range. A call to _error_msg(fault_type, 
text _j)tr, line_num, value, limit) is made with fault _type set to 1. text _ptr points 
to the filename, line_num is the line number, value is the bad index value, and 
limit is the index limit. 

Input: UI32 out of range index value in register DXAX 



< pointer size> -bit pointer at TOS to information 



block of the form: 
UI16 index limit 
UI32 line number 



Filename (variable number of bytes) 
0 (Filename terminator) 



Output: 



None. 



Registers Destroyed: 



N/A 



Side Effects: 



This routine may not be returned from. 



Synopsis: 



Call _error_msg(fault_type, textjtr, line_num, value, 
limit) and never return. 
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Pointer and Range Fault Routines 



FAULT_UI16< size> 

Traps the appropriate error when an unsigned integer variable is checked and 
found to be outside of a predefined range. A call to _error_msg(fault_type, 
text _ptr, line_num, value, limit) is made with fault _type set to 2. text _ptr points 
to the filename, line_num is the line number, value is the bad index value, and 
limit is the index limit. 



Input: 



Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



UI16 out of range index value in register AX. 

< pointer size> -bit pointer at TOS to information 

block of the form: 

UI16 Index limit. 

UI32 Line number. 

Filename (variable number of bytes). 

0 (Filename terminator). 

None. 

N/A 

This routine may not be returned from. 

Call _error_msg(fault_type, text_ptr, line_num, value, 
limit) and never return. 
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Pointer and Range Fault Routines 



FAULT UI8< size> 



Traps the appropriate error when an unsigned char variable is checked and 
found to be outside of a predefined range. A call to _error_msg(fault_type, 
text _j)tr, line_num, value, limit) is made with faultjtype set to 3. text _ptr points 
to the filename, line_num is the line number, value is the bad index value, and 
limit is the index limit. 

Input: UI8 Out of range index value in register AL. 



< pointer size> -bit pointer at TOS to information 
block of the form: 
UI16 index limit 
UI32 

Line number. 

Filename (variable number of bytes). 
0 (Filename terminator) 



Output: 



None. 



Registers Destroyed: 



N/A 



Side Effects: 



This routine may not be returned from. 



Synopsis: 



Call _error_msg(fault_type, textjitr, line_num, value, 
limit) and never return. 
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Pointer and Range Fault Routines 



FAULT_I32< size> 

Traps the appropriate error when a signed long variable is checked and found 
to be outside of a predefined range. A call to _error_msg(fault_type, text_ptr, 
line_num, value, limit) is made with faultjtype set to 4. text _ptr points to the 
filename, line_num is the line number, value is the bad index value, and limit is 
the index limit. 



Input: 



Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



132 out of range index value in register DXAX. 

< pointer size> -bit pointer at TOS to information 

block of the form: 

UI16 Index limit. 

UI32 Line number. 

Filename (Variable number of bytes). 

0 (Filename terminator) 

None. 

N/A 

This routine may not be returned from. 

Call _error_msg( faultjtype, text_ptr, line_num, value, 
limit) and never return. 



323 



Chapter 1 1 : Run-Time Routines 

Pointer and Range Fault Routines 



FAULT I16<s/ze> 



Traps the appropriate error when a signed integer variable is checked and 
found to be outside of a predefined range. A call to _error_msg(fault_type, 
text _j)tr, line_num, value, limit) is made with faultjtype set to 5. text _ptr points 
to the filename, line_num is the line number, value is the bad index value, and 
limit is the index limit. 

Input: 116 out of range index value in register AX. 



< pointer size> -bit pointer at TOS to information 

block of the form: 

UI 16 Index limit 

UI32 Line number. 

Filename (Variable number of bytes). 

0 (Filename terminator) 



Output: 



None. 



Registers Destroyed: 



N/A 



Side Effects: 



This routine may not be returned from. 



Synopsis: 



Call _error_msg(fault_type, textjtr, line_num, value, 
limit) and never return. 
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Pointer and Range Fault Routines 



FAULT_I8< size> 

Traps the appropriate error when a signed char variable is checked and found 
to be outside of a predefined range. A call to _error_msg(fault_type, text_ptr, 
line_num, value, limit) is made with faultjtype set to 6. text _ptr points to the 
filename, line_num is the line number, value is the bad index value, and limit is 
the index limit. 



Input: 



Output: 

Registers Destroyed: 
Side Effects: 
Synopsis: 



18 out of range index value in register AL. 

< pointer size> -bit pointer at TOS to information 

block of the form: 

UI16 Index limit. 

UI32 Line number. 

Filename (Variable number of bytes). 

0 (Filename terminator) 

None. 

N/A 

This routine may not be returned from. 

Call _error_msg( faultjtype, text_ptr, line_num, value, 
limit) and never return. 
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Stack Frame Figures 

This section contains the figures that are referred to throughout this appendix. 



High Address 



Stack pointer (SP) 
Low Address 



Used stack space 



[msw] 
64-bit source and/or 
result operand 
[lsw] 



Caller's return 
address 

Top of stack 
(unused stack space) 



PARMO (8 bytes) 



segmentioffset if large model 



Figure 11-1. Stack Frame with Double Parameter 
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Stack Frame Figures 



High Address 



Stack pointer (SP) 
Low Address 



Used stack space 



[msw] 
64-bit left source 
and/or result 
operand 
[lsw] 



[msw] 
64-bit right source 
operand 
[lsw] 

Caller's return 
address 

Top of stack 
(unused stack space) 



PARM1 (8 bytes) 



PARMO (8 bytes) 



segment :offset if large model 



Figure 11-2. Stack Frame with Two Double Parameters 
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Stack Frame Figures 



High Address 



Stack pointer (SP) 
Low Address 



Used stack space 



[msw] 
32-bit source and/or 
result operand 
[lsw] 



Caller's return 
address 

Top of stack 
(unused stack space) 



PARMO (4 bytes) 



segmentioffset if large model 



Figure 11-3. Stack Frame with Float or Long Parameter 



High Address 



Stack pointer (SP) 
Low Address 



Used stack space 



[msw] 
32-bit left source 
and/or result 
operand 
[lsw] 



[msw] 
32-bit right source 
operand 
[lsw] 

Caller's return 
address 

Top of stack 
(unused stack space) 



PARM1 (4 bytes) 



PARMO (4 bytes) 



segmentioffset if large model 



Figure 11-4. Stack Frame with 2 Float/Long Parameters 
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12 



Behavior of Math Library Functions 

Results of math library functions for various types of floating-point input 
values. 
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The first table which follows describes the behavior of the math library 
functions which are passed a single parameter. The remaining tables describe 
the math library functions which are passed two parameters. 

Wherever the result is an exception, the IEEE defined return value is also 
listed. The IEEE defined value is returned if trapping on that exception is 
disabled. (See the _fp_error description in the "Libraries" chapter for 
information on enabling/disabling trapping on floating-point exceptions.) 



NUMBER TYPES 


EXCEPTION TYPES 


D 


Denormalized number 


DBZ 


Divide by zero 


N 


Normalized number 


DMN 


Domain error 


NaN 


Not a number 


IOP 


Invalid operation 


R 


Real number 


OVR 


Overflow 


x,y 


Function input 


RNG 


Range error 


[ ] 


Possible result 


TLS 


Total loss of significance 




UND 


Underflow 



Figure 12-1 . Legend for Math Library Behavior Tables 
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Table 1 2-1 . Behavior of Functions with One Parameter 





FUNCTION INPUT 


Funct. 


-oo 


-N 


-D 


-0 


+ 0 


+ D 


+N 


+00 


NaN 


acos 


IOP NaN 


[IOP NaN] 


TC/2 


7C/2 


7C/2 


7C/2 


[IOP NaN] 


IOP 
NaN 


X 


asin 


IOP NaN 


[IOP NaN] 


X 


0 


0 


X 


[IOP NaN] 


IOP 
NaN 


X 


at an 


-71/2 


R 


X 


0 


0 


X 


R 


7C/2 


X 


ceil 


-oo 


R 


0 


0 


0 


1 


R 


+00 


X 


cos 


IOP NaN 


[TLS NaN] 


1 


1 


1 


1 


[TLS NaN] 


IOP 
NaN 


X 


cosh 


+oo 


[OVR +°°] 


1 


1 


1 


1 


[OVR +oo] 


+oo 


X 


exp 


0 


[ UND 0.0] 


1 


1 


1 


1 


[OVR +oo] 


+oo 


X 


floor 


-oo 


R 


-1 


0 


0 


0 


R 


+00 


X 


frexp 


IOP NaN 


R 


R 


0 


0 


R 


R 


IOP 
NaN 


X 


ldexp 


-oo 


R 


R 


0 


0 


R 


R 


+00 


X 


log 


IOP NaN 


IOP NaN 


IOP NaN 


IOP 
-oo 


IOP 
-oo 


R 


R 


+oo 


X 


loglO 


IOP NaN 


IOP NaN 


IOP NaN 


IOP 
-oo 


IOP 
-oo 


R 


R 


+00 


X 


modf 


IOP NaN 


R 


R 


0 


0 


R 


R 


IOP 
NaN 


X 


sin 


IOP NaN 


[TLS NaN] 


X 


0 


0 


X 


[TLS NaN] 


IOP 
NaN 


X 


sinh 


-oo 


[OVR -oo] 


1 


1 


1 


1 


[OVR +oo] 


+oo 


X 


sqrt 


IOP NaN 


IOP NaN 


IOP NaN 


0 


0 


R 


R 


+00 


X 


tan 


IOP NaN 


[TLS NaN] 


X 


0 


0 


X 


[TLS NaN] 


IOP 
NaN 


X 


tanh 


-1 


R 


X 


0 


0 


X 


R 


1 


X 
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Table 12-2. "atan2" Behavior 



atan2(x,y) 


y 


-OO 


-N 


-D 


-0 


+ 0 


+ D 


+ N 


+ oo 


NaN 




-oo 


IOP 

NaN 


-7C/2 


-7C/2 


-7C/2 


-7C/2 


-7C/2 


-7C/2 


IOP 

NaN 


y 




-N 


-71 


R 


R 


-7C/2 


-7C/2 


R 


R 


0 


y 




-D 


-71 


R 


R 


-7C/2 


-7C/2 


R 


R 


0 


y 




-0 


-71 


-K 


-K 


IOP0 


IOP0 


0 


0 


0 


y 


X 


+ 0 


K 


K 


K 


IOP0 


IOP0 


0 


0 


0 


y 




+ D 


K 


R 


R 


7C/2 


71/2 


R 


R 


0 


y 




+ N 


K 


R 


R 


7C/2 


7C/2 


R 


R 


0 


y 




+ OO 


IOP 

NaN 


7C/2 


7C/2 


7C/2 


71/2 


7C/2 


7C/2 


IOP 

NaN 


y 




NaN 


X 


X 


X 


X 


X 


X 


X 


X 


X 
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Table 12-3. 'pow" Behavior 



pow(x,y) 


y 


-OO 


-N 


-D 


-0 


+ 0 


+ D 


+ N 


+ oo 


NaN 




-oo 


0 


0 


0 


1 


1 


IOP+oo 


[IOP+ /-oo] 


IOP+ °° 


y 




< -1 


0 


R 


R 


1 


1 


R 


R 


IOP+oo 


y 




= -1 


IOP 1.0 


R 


R 


1 


1 


R 


R 


IOP 1.0 


y 




>-l,<0 


IOP 

+ oo 


R 


R 


1 


1 


R 


R 


0 


y 




-0 


IOP 

NaN 


IOP 

NaN 


IOP 

NaN 


IOP 

NaN 


IOP 

NaN 


0 


0 


0 


y 


X 


+ 0 


IOP 

NaN 


IOP 

NaN 


IOP 

NaN 


IOP 

NaN 


IOP 

NaN 


0 


0 


0 


y 




>0,< 1 


+ OO 


R 


R 


1 


1 


R 


R 


0 


y 




= + 1 


1.0 


R 


R 


1 


1 


R 


R 


1.0 


y 




> + 1 


0 


R 


R 


1 


1 


R 


R 


+ oo 


y 




+ oo 


0 


0 


0 


1 


1 


+ oo 


+ oo 


+ oo 


y 




NaN 


X 


X 


X 


X 


X 


X 


X 


X 


X 



Table 12-4. "add" Behavior 



add(x,y) 


y 


-OO 


-N 


-0 


+ 0 


+ N 


+ oo 


NaN 




-oo 


-OO 


-OO 


-oo 


-oo 


-OO 


IOP NaN 


y 




-N 


-oo 


R 


X 


X 


R 


+ oo 


y 




-0 


-oo 


y 


-0 


+ 0 


y 


+ oo 


y 


X 


+ 0 


-oo 


y 


+ 0 


+ 0 


y 


+ oo 


y 




+ N 


-oo 


R 


X 


X 


R 


+ oo 


y 




+ OO 


IOP NaN 


+ oo 


+ oo 


+ oo 


+ oo 


+ oo 


y 




NaN 


X 


X 


X 


X 


X 


X 


X 
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Table 12-5. 'sub" Behavior 



sub(x,y) 


y 


-OO 


-N 


-0 


+ 0 


+ N 


+ OO 


NaN 




-oo 


IOP NaN 


-OO 


-OO 


-OO 


-OO 


-OO 


y 




-N 


+ OO 


R 


X 


X 


R 


-OO 


y 




-0 


OO 


-y 


+ 0 


-0 


-y 


-OO 


y 


X 


+ 0 


+ OO 


-y 


+ 0 


+ 0 


-y 


-OO 


y 




+ N 


+ OO 


R 


X 


X 


R 


-OO 


y 




+ OO 


+ OO 


+ OO 


+ OO 


+ OO 


+ OO 


IOP NaN 


y 




NaN 


X 


X 


X 


X 


X 


X 


X 



Table 12-6. 'niul" Behavior 



mul(x,y) 


y 


-OO 


-N 


-0 


+ 0 


+ N 


+ OO 


NaN 




-OO 


-|- OO 


+ OO 


IOP NaN 


IOP NaN 


-OO 


-OO 


y 




-N 


+ OO 


+ R 


+ 0 


-0 


-R 


-OO 


y 




-0 


IOP NaN 


+ 0 


+ 0 


-0 


-0 


IOP NaN 


y 


X 


+ 0 


IOP NaN 


-0 


-0 


+ 0 


+ 0 


IOP NaN 


y 




+ N 


-OO 


-R 


-0 


+ 0 


+ R 


OO 


y 




+ OO 


-OO 


-OO 


IOP NaN 


IOP NaN 


+ OO 


-|- OO 


y 




NaN 


X 


X 


X 


X 


X 


X 


X 
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Table 12-7. "div" Behavior 



div(x,y) 


y 


-OO 


-N 


-0 


+ 0 


+ N 


+ OO 


NaN 




-oo 


IOP NaN 


+ OO 


+ OO 


-OO 


-OO 


IOP NaN 


y 




-N 


+ 0 


+ R 


DBZ +oo 


DBZ -oo 


-Pv 


-0 


y 




-0 


+ 0 


+ 0 


IOP NaN 


IOP NaN 


-0 


-0 


y 


X 


+ 0 


-0 


-0 


IOP NaN 


IOP NaN 


+ 0 


+ 0 


y 




+ N 


-0 


-Pv 


DBZ -oo 


DBZ +oo 


+ R 


+ 0 


y 




+ OO 


IOP NaN 


-OO 


-OO 


+ OO 


+ OO 


IOP NaN 


y 




NaN 


X 


X 


X 


X 


X 


X 


X 



Table 12-8. "fmod"and "frem" Behaviors 



fmod(x,y) 
frem(x,y) 


y 


-OO 


-N 


-0 


+ 0 


+ N 


+ OO 


NaN 




-OO 


IOP NaN 


IOP NaN 


IOP NaN 


IOP NaN 


IOP NaN 


IOP NaN 


y 




-N 


X 


+ R 


IOP NaN 


IOP NaN 


-R 


X 


y 




-0 


-0 


-0 


IOP NaN 


IOP NaN 


-0 


-0 


y 


X 


+ 0 


+ 0 


+ 0 


IOP NaN 


IOP NaN 


+ 0 


+ 0 


y 




+ N 


X 


+ R 


IOP NaN 


IOP NaN 


+ R 


X 


y 




+ OO 


IOP NaN 


IOP NaN 


IOP NaN 


IOP NaN 


IOP NaN 


IOP NaN 


y 




NaN 


X 


X 


X 


X 


X 


X 


X 
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13 



Comparison to C/64000 

Information needed to convert files from C/64000. 
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General C/64000 Options 



The 8086/186 C Cross Compiler is more similar to native C implementations 
than C/64000. Specifically, it supports register variables as intended by C and 
it includes a robust set of support libraries. 

Another area in which this implementation of C differs significantly from 
C/64000 is in the area of compiler options. A list of the C/64000 options 
follows (both general and processor-specific), and comparable options of this 
implementation are described. Note that many C/64000 options could be 
specified in the source file and, thus, could be varied within the file; some of 
the 8086/186 C compiler's comparable options are specified on the command 
line and affect the entire file. 

All of the absolute (.X) files generated by the 8086/186 C Cross Compiler use a 
data bus width of 16 bits. If you used the directives "8088" or "80188" with 
C/64000, be aware that you must now specify the data bus width when 
programming PROMs. Thus instead of 

program from file.X start 0 rom addr 0 

you should use 

program from file.X start 0 rom addr 0 system rom data width 0 

If you do not specify the data width, the PROM will contain only alternate 
bytes from the file. 



General C/64000 Options 

AMNESIA 

This directive in C/64000 encompassed two distinct compiler concerns which 
are addressed separately in this compiler. First, it was intended to allow for 
memory mapped I/O locations or locations which could change in value as a 
result of an asynchronous event such as an interrupt. Second, it was intended 
to defeat a limited form of common subexpression elimination implemented 
in C/64000. Both of these intents are addressed by the ANSI standard 
qualifier volatile in this implementation. 
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General C/64000 Options 

ASMFILE 

This is not implemented. A listing with embedded assembly can be provided 
with the "listing" and "add assembly code to listing" command line options; the 
"generate assembly source files" option causes assembly source files to be 
created. 

ASMBSYM 

HP format "asmb_sym" files can be generated via a command line option. 

DEBUG 

This occurs by default. The "strip symbol table information" command line 
option will remove debug symbols. 

EMITCODE 

This is implemented by a command line option. 

ENDORG 

This was used to terminate an ORG'd segment. In the new compiler, ORG 
functionality is accomplished via the SEGMENT pragma which is terminated 
by another SEGMENT pragma. 

ENTRY 

This is handled by the crtO or crtl routines to which programs are linked. 

EXTENSIONS 

This is not supported. 

FIXEDPARAMETERS 

The intention of this option was to allow the calling of PASCAL/64000 
routines from C/64000 routines. This capability can be accomplished through 
the ASM pragma. 



339 



Chapter 13: Comparison to C/64000 

General C/64000 Options 



FULLLIST 

This is implemented by specifying all the command line options which affect 
the listing sent to the standard output. 

INIT_ZEROS 

The main purpose of this option was to avoid large compiler output 
containing primarily zero initializers for large arrays. This is not a problem 
with the new assemblers and object file formats which can express large 
initializers more compactly. There is a related option which gives warnings 
that no load-time initialization can occur. 



LINE NUMBERS 

This occurs by default. The "strip symbol table information" command line 
option will remove line number symbols. 

LIST 

This is handled from the command line with the 'listing" option. 

LISTCODE 

This is handled from the command line with the 'listing" option in addition to 
the "add assembly code to listing" option. 

LISTOBJ 

Object listing is always given with "add assembly code to listing" option 
(specified in addition to the "listing" option). 

LONG_NAMES 

All internal names in this compiler have 255 character significance; external 
names have 30 character significance. 
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General C/64000 Options 



OPTIMIZE 

This is implemented via the "optimize" command line option. 

ORG 

This is implemented via the SEGMENT pragma. 

PAGE 

A page break can be generated by inserting a form feed in the source. 

RECURSIVE 

This is not implemented since, in C, the user may declare local variables to be 
static (the only potential gain of this option). 

SEPARATE 

This option had no effect in the C/64000 8086/186 C compiler and is not 
implemented in this compiler. However, the SEGMENT pragma permits 
control over the segments in which program, data, and constants are placed. 

SHORTARITH 

This is not implemented. However, the new C is able to perform arithmetic 
calculations on floats without expanding to double which provides much of the 
savings that this option provided. 

STANDARD 

This is not implemented. 

TITLE 

This is not supported. 
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UPPER_KEYS 

This is not supported. 

USERDEFINED 

This is not implemented. 

WARN 

This is implemented via the "suppress warning messages" command line 
option. 

WIDTH 

This option caused the 64000/C compiler to read only a portion of a source file 
line (e.g., the first 80 characters). This option has no equivalent in the 
8086/186 C compiler. 



8086-Specific C/64000 Options 

ALIGN 

By default, data and constants larger than one byte are aligned to a word 
boundary for efficient access. When the 'byte align data" compiler option is 
used, data and constants are no longer necessarily aligned to a word boundary. 

CS_EXTVARS, ES_EXTVARS, SS_EXTVARS 

These are not implemented 



DS_EXTVARS, FAR EXTVARS 

These are in effect supported. These are implemented via the SEGMENT 
pragma and the command line option that controls the memory model. 
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8086-Specific C/64000 Options 

FARLI BR ARIES, SHORTLIBRARIES 

These are not implemented. The FAR and NEAR aspects correspond to the 
large and small memory models respectively. 

FAR_PROC, POINTER_SIZE 

These can be implemented by choice of memory model and the "near calls" 
command line option in the large memory model. 

INT 

This is not implemented since the functionality can be accomplished by coding 
the "INT" with in-line assembly (see ASM and END_ASM pragmas). 

INTERRUPT 

This is implemented in the new C via the INTERRUPT pragma. 

SEPARATECONST 

Switch tables for "case" statements (jump vectors) are always placed in code 
segments. C constants (const declarations and strings) are put into their own 
CONST segment. Constants are ROMable in the large memory model, since 
the CONST segment can be placed adjacent to the PROG segment. In the 
small memory model, the CONST segment is more restricted in its placement 
in memory. See the section on "RAM and ROM Considerations" in the 
chapter "Embedded Systems Considerations" for more details. 



343 



Chapter 13: Comparison to C/64000 

Differences from HP 64818 Code 



Differences from HP 64818 Code 

This section describes: 

1 The differences between the HP 64818 and HP B1493 C compilers. 

2 Ways to convert code written for the HP 64818 so that it will work with 
the B1493C compiler. 

Alignment 

HP 64818 Word alignment is set by the $ ALIGN ON$ option. 

HP B1493 Word alignment is performed. Refer to the 

"Alignment Considerations" section in the "Internal 
Data Representations" chapter. 



Integral promotions 

HP 64818 

HPB1493 



A char, a short int, or an int bit-field, when used in 
an expression will be converted to an int unless 
$SHORT_ARITH ON$ is specified. 

The effect is the same as if integral promotions were 
always performed. 



Float promotions 

HP 64818 

HPB1493 



Promotion from a float to a double will be 
performed in an arithmetic operation unless 
$SHORT_ARITH ON$ is specified. 

Promotion from a float to a double will not be 
performed unless one of the operands is a double. 



344 



Chapter 13: Comparison to C/64000 

Differences from HP 64818 Code 



Shift operations 

HP 64818 

HPB1493 



To convert: 



Logical shift on all shift operations. Shift by a 
negative value will reverse the shift direction. 

Logical shift on all left shifts and on right shifts of 
unsigned expressions. Arithmetic shift is used on 
all right shifts of a signed expression. Shift by a 
negative value will cause unexpected behavior. 

Reverse the direction for every negative shift. Cast 
the expression to unsigned before the shift 
operation if logical shift is required. 



Operations on structures 



HP 64818 Structures maybe assigned, compared for equality, 

passed as parameters, or returned from functions. 

HP B1493 Structures maybe assigned, passed as parameters, 

and returned from functions. No comparison for 
equality is allowed. 

To convert: Comparison for equality between structures must 

be done with in-line code or with user supplied 
function calls. 



Symbol names 

HP 64818 

HPB1493 
To convert: 



The first 15 characters in a symbol name are 
significant. 

Internal names have 255 significant characters. 
External names have 30 significant characters. 

A23456789012345_bcd and 
A23456789012345_xyz are taken as two different 
symbols in HP B 1493. 
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Differences from HP 64818 Code 



Numeric constant formats 

HP 64818 $EXTENSIONS ON$ permits use of HP 64000 

format for defining binary, octal, decimal, and 
hexadecimal constants (e.g., OFFH). 

HP B1493 Supports the standard constant formats (e.g., Oxff). 



To convert: 



Conversion from HP 64000 format to C constant 
format (e.g., OFFH to Oxff) is needed. 



String constant allocation 



HP 64818 



Identical string constants or string constants that 
are a subset of another will be mapped into the 
same location to minimize space. 



HPB1493 



Each string constant will have its own memory 
space allocated in segment const. 



To convert: 



Affects only the assembly code that accesses the 
absolute location of the constant. 



Memory management 



HP 64818 



INITHEAP, INCREASEHEAP, NEW, DISPOSE, 
MARK and RELEASE are provided for dynamic 
memory management. 



HPB1493 



calloc( ),free( ), malloc( ), realloc( ), getmem(), and 

others are provided. 



To convert: 



Calls to INITHEAP, NEW, DISPOSE must be 
converted to calls to malloc( ), and/reef). Be aware 
that the calling sequences and the return values are 
different in these sets of functions. The heap is 
initialized during the provided program setup 
procedures for later use by getmem(). 
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Differences from HP 64818 Code 



Math functions 

HP 64818 

HPB1493 

To convert: 



ABS, SQRT, SIN, COS, ARCTAN, LN, and EXP 
are provided. 

abs( ), sqrt( ), sin( ), cos( ), atan( ), log( ), exp( ), and 
others are provided in the standard C arithmetic 
library. 

Calls to ABS, SQRT, SIN, COS, ARCTAN, LN, 
and EXP must be converted to calls to the 
corresponding function in the C math library. 



Passing a byte-sized parameter 



HP 64818 

HPB1493 
Passing a pointer 

HP 64818 

HPB1493 



All signed and unsigned scalar values are extended 
to a 16-bit value and then pushed on the stack. 

Same as HP 64818. 



Pointers are pushed on the stack as 16 or 32 bit 
quantities as specified by the $POINTER_SIZE n$ 
option. 

32-bit pointers are pushed on the stack for large 
memory model, 16-bit pointers for small memory 
model. 



Passing a floating-point value 

HP 64818 All floating point values are pushed on the stack as 

64 bit double precision qualities, with the least 
significant bytes in lower memory addresses. 

HPB1493 Same as HP 64818. 
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Passing a structure 

HP 64818 

HP B 1493 
Passing an array 
HP 64818 
HPB1493 
Function return values 
HP 64818 



Structures are pushed on the stack on word 
boundaries. The last word of the structure is passed 
first. 

Same as HP 64818. 



The address of the array is pushed on the stack. 
Same as HP 64818. 



HPB1493 



Removing parameters 



HP 64818 



One byte results will be returned in register BL, two 
byte results in register BX. Return values greater 
than two bytes will be saved in the location pointed 
to by the result address pushed by the calling 
routine. 

One byte results will be returned in register AL, two 
byte results in AX, three byte results in register pair 
DL, AX, and four byte results in register pair DX, 
AX. Return values greater than four bytes will be 
saved in the location pointed to by the result 
address pushed by the calling routine. This pointer 
may point to a static memory location, an automatic 
variable, or temporary space on the stack. 



If the $FIXED_PARAMETER$ option is OFF 
(default), the calling routine is responsible for 
removing parameters from the stack. If the option 
is ON, the parameters are removed by the called 
routine. 
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HP B1493 The calling routine is responsible for removing 

parameters from the stack. 

Assembly Code Considerations 

Stack frame management is different in the HP 64818 and HP B1493 
compilers, as you can see by the parameter passing differences listed above. 

The assemblers used with each of the compilers are also different. The HP 
B1449 assembler is used with the HP B1493 compiler. 

Refer to the 8086/186 Assembler, Linker, Librarian manual for a description of 
the differences between the assemblers. 

When converting assembly language routines, it is best to surround the 
routines with C function headers and tails and embed your assembly language 
instructions inside # pragma ASM and # pragma END_ASM directives. You 
may have to change the instructions which access the parameters and return 
values, but if you use the compiler generated symbols (SET equal to BP 
offsets), you will be protected should anything about the compiler ever change. 
Refer to the "Compiler Generated Assembly Code" chapter for information 
about the HP B1493 compiler's calling conventions. 
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Stack Models 

Diagrams of the five stack models used in the 8086/186 C Cross Compiler. 
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The stack models are: 

• Stack Model for Small Memory Model 

• Stack Model for Large Memory Model 

• Stack Model for Medium Memory Model 

• Stack Model for Compact Memory Model 

• Near Stack Model for Large and Compact Memory Model (The near stack 
model applies when the "near calls" option is used.) 

• Interrupt Stack Model for Large and Compact Memory Model 

• Interrupt Stack Model for Small and Medium Memory Model 
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Figure 15-2. Stack for Small Memory Model 
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Figure 15-3. Stack for Large Memory Model 
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Figure 15-4. Stack for Medium Memory Model 
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Figure 15-5. Stack for Compact Memory Model 
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Top of stack 



Figure 15-6. NEAR Stack for Large and Compact Model 
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Figure 15-7. Interrupt Stack for Large & Compact Model 
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Figure 15-8. Interrupt Stack for Small & Compact Model 
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About this Version 

How this version of the compiler differs from previous versions. 
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Version 4.01 

New memory models 

The compact and medium memory models are supported. The "-m compact" 
option tells the compiler to generate code for the compact memory model. 
The "-m medium" option tells the compiler to generate code for the medium 
memory model. 

Control of NOPs 

The -Wc,Hx option allows you to specify the number of NOPs between 
functions. The default number is 1. 

C+ + style comments 

C+ + style comments are now accepted by cpp8086. 

Enhanced -M option 

The compiler warns when a function is used without a previously declared 
prototype if the -M command-line option is used. 

New usage message 

cc086 prints a usage message if no options are used on the command line. 

Version 4.00 

New product number 

The product number has been changed to B1493 for all hosts. 

The old product number was 64904 (for HP 300/400 hosts), and B 1427 (for 
Apollo hosts — no longer supported). 



364 



Chapter 16: About this Version 

Version 3.50 

New command-line options 

The -Wo,m option tells the optimizer to avoid certain optimizations. 
The -K option enforces strict segment information consistency. 

New default environments 

All of the default environments supplied with the compiler are now HP 
64700-series emulators. 

Renamed run-time library routines 

Some run-time library routines have been renamed in anticipation of the 
addition of medium and compact memory models. Routines which will be 
supported by both the large and medium models now have a _LM suffix. 
Routines which will be supported by both the small and compact models have 
a JSC suffix. 

Re-organized manual 

The User's Guide and Reference manuals have been combined and the chapters 
have been re-organized a bit. 



Version 3.50 
Behavior of sprintf 

The behavior of the sprintf function is undefined if the destination array is also 
one of the other arguments. For example, the value of stringl is undefined 
after the following line of code: 

sprintf (stringl, "%s %d", stringl, integerl); 



This undefined behavior of sprintf is particularly important because the 
behavior has changed between versions of the compiler. 
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Version 3.50 

Formatted printing 

The formatted printing functions, such as printf and sprintf, use less stack 
space. They use 350 fewer bytes than in version 3.40 compilers. 

Streams 

The ungetc library function can now be used as the first operation on a stream. 

Void pointers 

Void pointers now maybe compared using the relational operators "< ", "< = ", 
">", and"> = ". 

qsort function 

The qsort function is now reentrant. 

The variable _qsort_buffer has been removed from the libc.a library. In 
previous versions of the compiler, this variable needed to be initialized in the 
program startup code. All references to _qsort_buffer should be removed. 

Environment library modules 

Previous versions of the compiler loaded some modules from env.a even 
though those modules were not used. The library has been restructured so that 
fewer modules will be loaded. 

You may need to load the environment library (env.a) twice to resolve all 
external references. The linker command files (for example, 
/usr/hp64000/env/hp6476x/iolinkcom.k) show how this can be done. 

Improved performance 

The compile speed has been significantly improved. @S2 = Code sharing 

You will see greatly reduced code size if you use sprintf or vsprintf and one of 
the file-oriented printf routines (printf, fprintf, vprintf, or vfprintf). These 
functions now share much of their code. 

The string versions of the printf routines are still reentrant. 
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asm ('C_string') function 

In addition to the # pragma ASM/END_ASM method of embedding assembly 

code in the C source, the 8086/186 C compiler supports the asm 

('C_string') function. (It is not a true function, but is treated syntactically as a 

function.) asm, which may only appear inside a function body just as any 

other function call might, outputs one or more lines of assembly to the output 
compiler-generated assembly code. The two leading underscores are required 
and are present to conform to ANSI name space requirements. 

The assembly language instructions are contained in the C_string argument. 
The compiler does not check the assembly instructions for correctness. It 
simply passes the instructions to the assembler. The C_string argument must 
contain whitespace and newlines so assembly instructions will conform to the 
format and syntax required by the HP B1449 Assembler. 

The asm function has two advantages over the ASM/END ASM pragmas: 

first, it maybe used in macro definitions, and second, it is sometimes more 
expedient for single instructions. 

Modifying function entry/exit code 

Three new pragmas are available in this release of the compiler. They are 
# pragma FUNCTION_ENTRY 'C_string", # pragma FUNCTION_EXIT 
'Cjstring", and # pragma FUNCTION_RETURN 'C_string". These pragmas 
allow you to insert embedded assembly code in the entry and exit code of a 
function. They are useful for monitoring and debugging function calls. 

New segment names 

All compiler-generated code is now placed in segments with the class name 
"CODE." Thus there are now segment names in the .k files such as "lib/CODE" 
and "libm/CODE" in place of "lib" and "libm." 

This change affects the iolinkcom.k, linkcom.k,fiolinkcom.k, and flinkcom.k 
files in /usr/hp64000/env/hp6476x/large, /usr/hp64000/env/hp6476xl small, and 
the corresponding directories for the other supported emulators. 

Library constants are no longer placed in the same segment as the code. The 
constants for "libc" and "libm" are now placed in segments "libcconst" and 
"libmconst," respectively. 
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If you will be using the .k that are shipped with the compiler, these changes 
will not affect you. If, however, you have modified .k files for a previous 
version of the compiler, you will need to add the new section names. 
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On-line Manual Pages 

Printed copies of the on-line documentation. 
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NAME cc8086 - C cross compiler for Intel 8086 microprocessor 

SYNOPSIS /usr/hp64000/bin/cc8086 [ options ] files 

/usi7hp64000/bin/cc80186 [ options ] files 

DESCRIPTION The cc8086 program is a C cross-compiler which generates object code for the 

Intel 8086 microprocessor. Cc80186 generates object code for the Intel 80186 
microprocessor. They accept several types of arguments: 

Arguments whose names end with .c are taken to be C source programs. They 
are compiled and each object program is left on the file whose name is that of 
the source with .o substituted for .c. The .o file is deleted only if a single C 
program is compiled and linked all in one step. 

In the same way, arguments whose names end with .s are taken to be assembly 
source programs and are assembled, producing a .o file. 

Arguments whose names end with .i are taken to be C source programs which 
have already been preprocessed (see -P). They are compiled without invoking 
cpp8086( \) and each object program is left on the file whose name is that of 
the source with .o substituted for .i. 

Arguments whose names end with .o are taken to be relocatable object files 
which are to be included in the link operation. 

Arguments can be passed to the compiler through the CC8086OPTS 
environment variable as well as on the command line. The compiler picks up 
the value of CC8086OPTS and places its contents before any arguments on the 
command line. For example (in sh(\) notation): 

CC8086OPTS= -v 
export CC8086OPTS 
cc8086 -L prog.c 

is equivalent to: 

cc8086 -v -L prog.c 

The compiler also checks the environment variable HP64000. If it has been set 
and exported, it is used as the directory path (in place of the default 
/usr/hp64000) for executables (e.g.,Aib/cpp8086), libraries specified by using -1 
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(e.g. Aib/8086AargeAibm.a), include files (e.g. Anclude/8086/stdio.h), and the 
default linker command file {/env/hp6476xAarge/iolinkcom.k). 

The following options are recognized by cc8086: 

-b 

Cause the compiler to use the Branch Validator preprocessor, which inserts 
additional code for branch counting. See bbacpp8086{\) . 

-c 

Suppress the link edit phase of the compilation and force an object (.o) file to 
be produced even if only one program is compiled. Produces a .o file for each 
.c file. 

-C 

Do not strip C-style comments in the preprocessor except those found on 
preprocessor directive lines. See cpp8086{\). 

-d 

Separate data output into initialized (non-constant data explicitly initialized 
with a C initializer) and uninitialized (non-constant data implicitly initialized 
to zero, in the absence of -u, at load time). The default output segments are 
udata and idata. See also # pragma SEGMENT. 

-D name= def 
-D name 

Define name to the preprocessor. See cpp8086{\). 
-e 

Turn off code generation allowing fast syntactic and semantic error checking 
of the source program. This option overrides the -L, -c, and -S options. 

-E 

Run only cpp8086{\) on the named C programs and send the result to the 
standard output. 

-f 

Generate 8087 (floatingpoint coprocessor) code for floatingpoint operations. 
This option causes code to be generated in-line for operations which might 
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otherwise be performed with run-time library calls. It also causes linker 
command file fiolinkcom.k (or flinkcom.k, if -N used) to be used. These linker 
command files use the 8087 run-time (Ub87.a) and math (Ubm87.a) library files. 

-g 

Generate additional (but less optimal) code which performs run-time error 
checking. Note that it is not necessary to use -g to get complete symbolic 
debugging. 

The two types of run-time checks made are: 

1) Dereferences of all NIL pointers and uninitialized automatic pointers 
are detected and reported. This requires the initialization of automatic 
pointers at run-time with a value (-1) indicating that they are 
uninitialized. Note that initialization of statics to the uninitialized pointer 
value is not possible, as statics default to zero. 

2) Array references outside declaration index bounds are detected and 
reported. 

This option overrides the -O or -s option, 
-h 

Cause generation of an HP 64000 format assembler symbol file, linker symbol 
file, and absolute file for debugging purposes. The assembler symbol file is 
named (source basename).A, the linker symbol file (output file name).L, and 
the absolute file (output file name).X. The symbol file names can be changed 
with the -H assembler or linker option passed via the -W option. 

-I dir 

Change the search algorithm used by the preprocessor for finding include files. 
Seecpp8086(l). 

-k linkcomfile 

Cause the named linkcomfile to be used by the linker rather than the default 
/usr/hp64000/env/hp6476x/large/iolinkcom.k (see also -f, -N and -r). 

Note that if the environment variable HP64000 is set and exported, the 
/usr/hp64000 part of the path for the default file becomes $HP64000. 

See ld86{\) for details about the format of linker command files. 

The -k option overrides any linker command file implications of the -f, 
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-N, -p, or -r options. 
-K 

Cause the compiler to strictly enforce section information for variables. By 
default, the compiler does not require that the section information between a 
symbol declaration and definition match exactly. This option forces the 
information to be identical. 

Section information for variables and functions are communicated to the 
compiler via the SEGMENT pragma. With this information the compiler can 
address different sections of code and data with different address modes. If a 
different section is named for a "extern" reference than the actual variable 
declaration, then undesired addressing modes could be used. This could lead 
to a defect in code generation that is very difficult to locate. Usage of the -K 
option will cause this type of coding error to be found at compile time. Its use 
is highly recommended. 

See also the discussion about # pragma SEGMENT, 
-lx 

Cause the linker to search the library /usr/hp64000/lib/8086/large/libx.a (or 
/usr/hp64000/lib/8086/small/libx.a if -m small is used, or /usr/hp64000/lib/ 
8086/medium/libx.a if -m medium is used, or /usr/hp64000/lib/8086/compact/ 
libx.a if -m compact is used, ). Use -1 "'to load lib.a. If the environment 
variable HP64000 is set and exported, the /usr/hp64000 part of the path 
becomes $HP64000. Note that -1 options must appear after any files which 
reference library routines, typically at the end of the command line. You do 
not need to use the -1 option if the library is loaded by the linker command file. 

-L[i][x] 

Cause the compiler to generate a listing file (suffixed with .O) for each C 
source compiled. This listing contains C source intermixed with generated 
assembly code. 

If the -S (do not assemble) option is present, the intermixed assembly is just as 
it appears in the .s file; otherwise, the intermixed assembly is taken from the 
assembler's listing file with program counters and object code. 

If the -i option is present, include files are expanded and included in the listing. 

If the -x option is present, a symbol cross-reference table is appended to the 
compiler listing and also to any assembler or linker listings. 
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If the assembler is invoked for any .s files on the command line, an assembler 
listing is produced in the corresponding listing file suffixed .O and -x invokes 
the assembler's cross-reference. 

If the linker is invoked, a linker listing is produced in a listing file named 
outfile.O (default a.out.O, see -o) and -x invokes the linker's cross-reference. 

Options which prevent compilation (-e, -E, and -P) prevent the generation of 
listings. 

-m memoryModel 

Cause the compiler to generate code for the selected memory model. If this 
option is not present, the large memory model is assumed. memoryModel may 
be either: 

large large memory model (default) 
small small memory model 
medium for the medium memory model 
compact for the compact memory model 

The small memory model has two segments which never change. One is a 
code segment (CS does not change). The other is a combined stack and 
DS-relative static data segment (DS, SS, and ES are identical and do not 
change). In this model all pointers are 16 bits. 

The large memory model may have one or more code segments (CS may 
change); one independent stack segment (SS does not change); zero or one 
DS-relative static data segment for each C function (DS may change); and 
zero, one, or more ES-relative static data segments (ES may change). In this 
model all pointers are 32 bits. Functions are considered to be "FAR" and are 
called as such except when a static function is encountered and the -n option is 
in effect. 

The medium memory model may have one or more code segments (the CS 
register may change) and one data segment (the DS, SS, and ES registers are 
identical and do not change). The function pointer size is 32 bits, and the data 
pointer size is 16 bits. 

The compact memory model has one fixed code segment (the CS register does 
not change) and one or more data segments (the DS, SS, and ES registers are 
not identical and may change). The function pointer size is 16 bits, and the 
data pointer size is 32 bits. 

-M 
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Cause the compiler to generate more warning messages for possible errors in 
the C source than are generated by default. 

-n 

Cause all static functions in large memory model to be called "NEAR". This 
option should be used only when the user can guarantee that all static 
functions within the source file(s) being compiled are called from the same 
segment and that no pointer arithmetic is being performed to generate the 
call. This option is ignored in the presence of -m small. 



-N 

Cause the compiler to link using the linkcom.k (flinkcom.k, if -f used) linker 
command file rather than the iolinkcom.k (fiolinkcom.k, if -f used) command 
file. The \f\linkcom.k command file loads the crtl.o program setup routine 
which does not open stdin, stdout, or stderr. -N is overridden by the -k option, 
but works in conjunction with the -r option. 

-o outfile 

Name the output file from the linker outfile.x (or outfile.X and outfile.L, if the 
-h option is specified). Outfile is a.out by default. 

-0[G][T] 

Generate locally optimal code and invoke an assembly code optimizer. Code is 
optimized for space (even, possibly, at the expense of time) unless -T is also 
specified. 

If the -T option is present, code is optimized for time whenever time and space 
optimizations conflict. If the -G option is present, additional code is generated 
(as it is when -O is not used) to make the program easier to debug using an HP 
emulator or debugger. This includes: 

1) Generation of no-operation (NOP) instructions preceding all labels. 
This provides unique addresses for all labels. Note that the peephole 
optimizer will remove any of these no-operation instructions that it 
considers to be dead code (following an unconditional branch). 

2) Buffering of the frame-pointer on the stack at function entry and 
restoration of the frame-pointer at function exit, even when this is known 
not to be necessary. 
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The -O option is overridden by the -g option. 



-P 



Run only cpp8086( \) on the named C programs and leave the result on 
corresponding files suffixed .i. 



Cause the compiler to byte align data in memory, rather than the default word 
alignment. Data of types short, int, long, pointer, float, double, struct, and 
union will be aligned on byte rather than word boundaries. Data of types 
struct and union will not be padded. Note that the size of structures and 
unions as well as the offsets of their members are affected by this option. 
Therefore, modules which define structures or unions and those which 
reference them or their members must both be compiled with the same 
alignment. For the sake of safety, it is recommended that all sources linked 
together be compiled with the same alignment, libc.a, libm.a, and the run-time 
(lib.a) and environment libraries (env.a) are compatible with modules 
compiled under either alignment. 



Cause the compiler to use default linker command files iolinkcom.k, linkcom.k, 
fiolinkcom.k, or flinkcom.k (see -N and -f) in run-time environment directory 
/usr/hp64000/env/iii>/large (or /usr/hp64000/env/<ii>/[mem_model] if -m 
[mem_model] present) rather than in the default 

/usr/hp64000/env/hp6476x/large. For the Intel family of the HP 64700 series of 
emulators, the run-time environment is hp6476x. If the environment variable 
HP64000 is set and exported, the /usr/hp64000 part of the path for the above 
environments becomes $HP64000. The -r option is overridden by the -k 
option, but works in conjunction with the -N and -m options. 



Cause the output of the compiler, assembler, and linker to be stripped of 
symbol table information. The use of this option will prevent the use of 
symbols for analysis/debug purposes in any consumers of the executable. This 
option is overridden by the -g option and, for file and line information, by the 
-L option. 




-Q 



■r dir 



-s 



-S 
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Compile the named C programs and leave the assembly language output on 
corresponding files suffixed .s. This option prevents invocation of the 
assembler. 

-t c,name 

Substitute or insert subprocess c with name where c is one or more of a set of 
identifiers indicating the subprocess(es). This option works in one of two 
modes: 

1) If c is a single identifier, name represents the full path name of the new 
subprocess. For example: cc8086 -tp,/mydir/cpp source.c 

2) If c is a set of identifiers, name represents a prefix to which the standard 
suffixes are concatenated to construct the full path names of the new 
subprocesses. For example: cc8086 -tpc2L,/mydir/ -tal,/mydir2/ source.c 

c can be one or more of the following identifiers: 



p preprocessor (standard suffix is cpp8086) 

c compiler body (standard suffix is ccom8086L or ccom8086S) 

0 same as c 

0 optimizer (standard suffix is opt8086) 
2 same as o 

m macro preprocessor for assembler (standard suffix is ap86) 

a assembler (standard suffix is as86) 

L lister (standard suffix is clst8086) 

1 linker (standard suffix is ld86) 



Note also in this context that the standard processes invoked are named: 
/usr/hp64000/lib/cpp8086 

/usr/hp64000/lib/ccom8086L (or ccom8086S, ccom8086C, or ccom8086M) 

/usr/hp64000/lib/opt8086 

/usr/hp64000/bin/ap86 

/usr/hp64000/bin/as86 

/usr/hp64000/lib/clst8086 

/usr/hp64000/bin/ld86 
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If the environment variable HP64000 is set and exported, the /usr/hp64000 part 
of the path for the above files becomes $HP64000. 

-u 

Cause the compiler to consider all non-constant static data as uninitialized 
and to issue a warning whenever an initializer is placed on such static data. 
This option is useful for embedded environments where no load-time 
initialization is possible (as opposed to environments, such as emulation or 
simulation, where load-time initialization of static data is possible only when 
the user loads the memory). 

-U name 

Remove any initial definition of name, where name is a reserved symbol that is 
predefined by the preprocessor or a symbol defined by a -D option regardless 
of the order of the options. Normally, cc(l) predefines symbols that reflect 
simultaneously the host and execution environment. Since cc8086 is a cross 
development tool, it predefines one symbol indicating the cross environment 
and one target processor symbol. Additionally, a symbol is predefined to 
indicate which memory model is being used. The reserved symbols are: 

cross environment: hp64000 

target processor: i8086 

memory model: _LARGE JVIODEL or SMALL_MODEL or 

MEDIUM_MODEL or _COMPACT_MODEL 

-v 

Enable verbose mode, producing a step-by-step description of the compilation 
process on stderr. 

-vv 

Suppress warning messages. 
-W c,argl[,arg2,...,argN] 

Cause argl through argN to be passed as parameters to subprocess c of the 
compilation process. The args are of the form -argoption[,argvalue], where 
argoption is the name of an option to be passed to the subprocess and argvalue 
is an argument to argoption. The valid values for c are those listed under the -t 
option. For example, to invoke the -t option of clst8086(\): cc8086 -L -WL,-t 
source.c 
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Note that options other than the above are not recognized and cause a 
warning message to be written to stderr. 

The following options to ccom8086 are accessible via the -W option described 
above: 

-C segname 

Change the default segment name for constant output (see CONST under 

# pragma SEGMENT below) from the default const to the argument, segname. 



-D segname 

-D segnamel,segname2 

If one argument is given, change the default segment name for data output 
(see DATA under # pragma SEGMENT) from the default data to the 
argument, segname. 

If two arguments are given, change the default segment name for uninitialized 
data output (see UD ATA under # pragma SEGMENT) from the default udata 
to the first argument, segnamel, and change the default segment name for 
initialized data output (see ID ATA under # pragma SEGMENT) from the 
default idata to the second argument, segname2. 

-F 

Turn off the compiler's automatic creation of register variables for addresses 
of statics and frequently used variables. 

-1 prefix 

Alter the compiler's algorithm for creating assembly language labels from C 
symbols. Rather than using an underscore at the beginning of such labels, the 
compiler will use prefix. Since the default prefix is '_', it is used as a special case 
for specifying that no prefix be used via -Wc,-1_. This option should be used 
with great care as it may generate assembly-time and/or link-time errors due 
to conflicts between compiler-generated assembly language labels and other 
assembly symbols. See also # pragma ALIAS. 

-N modulename 

Cause the compiler to use modulename for the argument to the NAME 
directive in the assembly source produced rather than the default modulename 
which is the C source file basename (see basename(l)). 
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-P segname 

Change the default segment name for program output (see PROG under 

# pragma SEGMENT) from the default prog_basename to the argument, 

segname. 

In addition to standard C in the C source files, cc8086 accepts and ignores all 
pragmas except the following: 

# pragma ALIAS Csymbolname Assemblysymbolname 

# pragma ALIAS Csymbolname """Assemblysymbolname""" 

This pragma allows overriding of the C compiler's algorithm for converting a 
C source file symbol name into a unique assembler symbol name (the 
algorithm generally prepends an "_" or "S_"). This pragma must be placed 
before any references to the symbol. This pragma should be used with great 
care as it may generate assembly-time and/or link-time errors due to conflicts 
between Assemblysymbolname and other assembly symbols. Use the quotation 
marks if the Assemblysymbolname would not be a valid C identifier. 

# pragma ASM 

# pragma END_ASM 

These pragmas are used to bracket sections of assembly code which are 
inserted into the assembly code generated by the compiler. The assembly code 
optimizer assumes that working registers AX, BX, CX, DX, DI, processor 
status word (PSW), ST(0) and ST(1) when using -f, and in large memory 
model ES are destroyed in embedded assembly code sections; therefore, they 
maybe freely used. The register variable (SI), the frame pointer (BP), the 
stack pointer (SP), the segment registers (CS, DS, SS, and, for small memory 
model, ES), and the floatingpoint register variables (ST(2) through ST(6)) 
when using -f are not buffered prior to embedded assembly language sections. 
So, inadvertently writing over one of these registers should be avoided. Also, 
when using the -f option the 8087 stack pointer must not be left in an altered 
state and ST(7) must be "free". Embedded assembly code may reference C 
variables. The compiler incorporates the C name of variables and functions 
into their corresponding assembly code symbols facilitating the referencing of 
C variables from embedded assembly code. In particular: externs, globals, 
statics, and functions have an underscore (_) prepended to their C name and, 
for each parameter and automatic, an assembly-time constant is created by 
prepending S_ to its C name. This constant is a frame-pointer -relative offset 
used to access the parameter or automatic value. Because of scoping 
requirements and a 30 character significance limit on assembly names, C 
names longer than 29 characters and those which appear in nested scopes may 
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have an additional ASCII number prepended to make them unique. See the 
COMPILER GENERATED ASSEMBLY CODE chapter in the manual for a 
complete discussion and examples of assembly symbol name generation. The 
ASM pragma maybe used anyplace in a C source (i.e. inside or outside of a C 
function). 

# pragma DS segmentName 

This pragma is only valid for large memory model; it is ignored in the presence 
of -m small. This pragma specifies that all subsequent functions should 
arrange to access any data in segment segmentName (rather than the default of 
the current DATA or UDATA segment name, see # pragma SEGMENT) using 
DS-relative addressing. If subsequent functions access any static data in 
segment segmentName, their preambles load DS with segmentName and use it 
in accesses. The effect of this is that once a DS pragma is used, the DS-relative 
segment name is fixed until another DS pragma is encountered. 

# pragma FUNCTION_ENTRY "C_String" 

# pragma FUNCTION_EXIT ^String" 

# pragma FUNCTION_RETURN "C_String" 

These pragmas also allow you to insert assembly code into the generated 
assembly code. They differ from the ASM pragma in several ways: 

They are not required to be paired and maybe used independently or together. 
They may only appear outside of a function body. They affect only a single 
function and must precede that function in the C source. They do not bracket 
the embedded assembly. Instead, the assembly is contained in the "C_String" 
argument. This argument is a C character string. It must contain whitespace 
and newlines so that when the compiler outputs the string to the generated 
source, it will conform to the format and syntax required by the assembler. 

# pragma FUNCTION_ENTRY will place the embedded assembly in a 
function's entry code. The embedded code appears immediately after the label 
generated from the function name in the C source and will precede the code 
generated for function entry. # pragma FUNCTION_EXIT will place the 
embedded assembly in a function's exit code. The embedded code appears 
after the code generated for the function exit and precedes the function return 
label. # pragma FUNCTION_RETURN will place the embedded assembly in a 
function's exit code. The embedded code appears after the return label. These 
pragmas give you the flexibility to modify the function entry and exit code. An 
example is using FUNCTION_RETURN to force an interrupt service routine 
to trap back to the operating system instead of simply returning to the point of 
interrupt. (See also # pragma INTERRUPT.) The information found under 
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# pragma ASM about accessing C symbols and about register buffering holds 
true for these pragmas as well. 

# pragma INTERRUPT 

This pragma specifies that the next encountered function be implemented as 
an interrupt routine. This means that all working registers are saved at 
function entry and restored prior to function exit (in addition to the register 
variable which ordinarily is buffered), no parameter passing or returned result 
is allowed, and a return from interrupt is generated at the return point. In the 
presence of the -f option, the 8087's complete internal state is saved. Note that 
only the next encountered function is affected— not subsequent functions. The 
INTERRUPT pragma maybe used anyplace a C external declaration may. 

# pragma SEGMENT [PROG= pname] [DATA= dname] [CONST= cname] 

# pragma SEGMENT [PROG= addr] [DATA= addr] [CONST= addr] 

# pragma SEGMENT [PROG= pname] [UDATA= udname] [IDATA= idname] 

[CONST= cname] 

# pragma SEGMENT [PROG= addr] [UDATA= addr] [IDATA= addr] 

[CONST= addr] 

# pragma SEGMENT UNDO 

# pragma SEGMENT [PROG= pname] [DATA= dname] [CONST= cname] 

# pragma SEGMENT [PROG= addr] [DATA= addr] 

[CONST= addr] 

# pragma SEGMENT [PROG= pname] [UDATA= idname] 

[IDATA= udname] [CONST= cname] 

# pragma SEGMENT [PROG= addr] [UDATA= addr] 

[IDATA= addr] [CONST= addr] 

# pragma SEGMENT UNDO 

This pragma is valid for large, medium, and compact memory model; it is 
ignored in the presence of -m small. The first form of this pragma causes the 
program, static data, and static constant information to be placed in segments 
named pname, dname, and cname respectively until the next SEGMENT 
pragma is encountered. This segment information is used for specifying the 
location of symbols to the linker. The linker expects to find external data in 
the segment whose name is active when the external declaration is made. In 
the second form, 20-bit physical addresses, whose syntax is the same as for C 
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constants, are given in place of the segment names causing the subsequent 
information to be ORG'd starting at the given address. The segment name 
associated with an ORG'd segment is of the form orghexaddress where 
hexaddress is the physical address where the segment is located. For example, 
org00012345H is located at 0x12345. The third and fourth forms listed are the 
same as the first two forms with UDATA and ID ATA substituted for data. 
These forms make sense only in the presence of the -d option which forces 
separation of explicitly initialized data from implicitly initialized (or 
uninitialized with -u) data. Non-constant static data items explicitly initialized 
by means of a C initializer go into the ID ATA named segment. Non-constant 
static data items not explicitly initialized by means of a C initializer go into the 
UDATA named segment. Always use DATA (as opposed to UDATA or ID ATA) 
to locate an external declaration in a segment. Note that changing DATA also 
changes both UDATA and ID ATA. The absolute addresses and segment names 
maybe intermixed for the three (four, counting UDATA and ID ATA) different 
information types (program, static data, static constant) in the same 
SEGMENT pragma. If the target segment is not specified for one of the 
information types, then it remains unchanged. The last form, # pragma 
SEGMENT UNDO, "undoes" the effect of the immediately preceding 
SEGMENT directive. That is, it restores the name (or address) of any segment 
renamed (or ORG'd) in the last directive. This form is useful at the end of 

# include files to restore the segment environment which existed prior to the 

# include file. (Include files should contain SEGMENT directives to define 
the segments that externs are in.) Default (without -d): 

PROG= prog_basename DATA= data CONST= const Default (with -d): 
PROG= pvogjbasename UDATA= udata IDATA= idata CONST= const 
basename is the C source file base name (see basename{\)) with all characters 
not legal for a segment name changed to underscore (_). 

Note that pragmas other than the above are not recognized and cause a 
warning message to be written to stderr. 



FILES 



file.c 



C source file 



file.s 



assembly source file 



file.o 



object file 



file.a 



library (archive) file 



/usr/hp64000/lib/cpp8086 



preprocessor 



/usr/hp64000/lib/ccom8086L 



compiler for large memory model 
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/usr/hp64000/lib/ccom8086S compiler for small memory model 

/usr/hp64000/lib/ccom8086C compiler for compact memory model 

/usr/hp64000/lib/ccom8086M compiler for medium memory model 

/usr/hp64000/lib/opt8086 optimizer 

/usr/hp64000/bin/ap86 macro preprocessor for assembler 

/usr/hp64000/bin/as86 assembler 

/usr/hp6400(Mib/clst8086 lister (C listing generator) 

/usr/hp64000/bin/ld86 linker 

/usr/hp64000/include/8086 standard directory for # include files 

Note that, when environment variable HP64000 is set and exported, it replaces 
7usr/hp64000" in all of the above file names. 

/usr/hp64000/lib/8086/large/lib.a run-time library 

/usr/hp64000/lib/8086/large/libc.a standard C support library 

/usr/hp64000/lib/8086/large/libm.a 

auxiliary math C support library 

/usr/h P 64000/lib/8086/large/lib87.a 

run-time library using 8087 

Aisr/hp64000/lib/8086/large/libm87.a 

auxiliary math C support library using 8087 

/usr/hp64000/env/hp6476x/large/env.a 

execution environment dependent library 

/usr/hp64000/env/hp6476x/large/iolinkcom.k 
default linker command file 

/usr/hp64000/env/hp6476x/large/linkcom.k 

linker command file when -N (no I/O) used 

/usr/hp64000/env/hp6476x/large/fiolinkcom.k 

linker command file when -f (8087 code) used 

/usr/hp64000/env/hp6476x/large/flinkcom.k 

linker command file when -N (no I/O) and -f (8087 code) used 
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/usr/hp64000/env/hp6476x/large/crt0.o 

default program setup routine 

/usr/hp64000/env/hp6476x/large/crt 1 .o 

program setup routine with no I/O initialization 

/usr/hp64000/env/hp6476x/large/div_by_0.o 

integer divide by zero interrupt routine 

/usr/hp64000/env/hp6476x/large/vector8087.o 8087 
exceptions interrupt routine 

Note that when the -m small (small memory model), -m medium (medium 
memory model), or -m compact (compact memory model) option is used the 
large in the above paths is changed to small, medium, or compact. 

/usr/hp64000/env/hp6476x/ioconfig.EA 

emulation configuration file corresponding to 
iolinkcom.k and fiolinkcom.k if present 

/usr/hp64000/env/hp6476x/config.EA 

emulation configuration file corresponding to 
linkcom.k and flinkcom.k if present 

/usr/hp64000/env/hp6476x/fioconfig.EA 

emulation configuration file corresponding to fiolinkcom.k 

/usr/hp64000/env/hp6476x/fconfig.EA 

emulation configuration file corresponding to flinkcom.k 

/usr/hp64000/env/hp6476x/src 

directory containing sources for environment 
dependent routines and emulation monitor 

See the -r option for easy access. 



AUTHOR The cc8086 program was developed by the Hewlett-Packard Company. 

SEE ALSO a P 86(l), ar86(l), as86(l), bbac PP 8086(l), clst8086(l), c PP 8086(l), ld86(l) 

B. W. Kernighan and D. M. Ritchie, The C Programming Language, Second 
Edition, Prentice-Hall, 1988 

HP 8086/186 C Cross Compiler User's Guide, Hewlett-Packard, 1995 
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DIAGNOSTICS cc8086 returns zero if no errors are detected during the compilation process, 

otherwise it returns non-zero. 

The diagnostics produced by cc8086 are intended to be self-explanatory. 
Occasional messages maybe written to stderrby the assembler. Error messages 
produced by the compiler are always written to stderr and consist of the 
original C source line on which the error was detected followed by a line 
containing a pointer to the token at which the error was detected and an 
explanatory message. Note that, for syntax errors, the token indicated will 
often be the token following the error. 
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cpp8086(1) 

NAME cpp8086 - C cross language preprocessor for Intel 8086 microprocessor 

SYNOPSIS /usi7hp64000/lib/cpp8086 [ options ] ifile [ ofile ] 

DESCRIPTION The cpp8086 command is the ANSI/ISO standard (9899-1990) C language 

preprocessor which is invoked as the first pass of any C compilation using the 
cc8086{\) command. Its purpose is to process include files, conditional 
compilation instructions, and macros. Thus the output of cpp8086 is designed 
to be in a form acceptable as input to the next pass of the C compiler. The 
preferred way to invoke cpp8086 is through the cc8086{\) command, since the 
functionality of cpp8086 may someday be moved elsewhere. Therefore, the 
direct invocation of cpp8086 is not recommended. See m4(l) for a general 
macro processor. 

The cpp8086 command optionally accepts one or two file names as arguments. 
The arguments ifile and ofile are respectively the input and output for the 
preprocessor. If ofile is not supplied it defaults to standard output. 

The following options to cpp8086 are recognized: 

-P 

Preprocess the input without producing the line control information used by 
the next pass of the C compiler. 

-C 

By default, cpp8086 strips C-style comments. If the -C option is specified, all 
comments (except those found on cpp8086 directive lines) are passed along. 

-U name 

Remove any initial definition of name, where name is a symbol defined by a -D 
option regardless of the order of the options. 

-D name 

-D name=def 

Define name as if by a # define directive. If no = def is given, name is defined as 
1. The -D option has lower precedence than the -U option. That is, if the same 
name is used in both a -U option and a -D option, the name is undefined 
regardless of the order of the options. 
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-I dir Add dirto the directory search list for # include files whose names do 
not begin with /. Thus, # include files whose names are enclosed in '\l "are 
searched for first in the directory of the file containing the # include line, then 
in directories named in -I options in left-to-right order. For # include files 
whose names are enclosed in <> , the directory of the file containing the 
# include line is not searched. However, all directories specified with -I 
options will still be searched. 

To access the standard header files shipped with the C compiler, add the 
directory /usr/hp64000/include/8086 to the search list via this option. 

-g 

Causes cpp8086 to generate file date and column position information. File 
date information is appended to the line and file synchronization information 
which is normally generated indicating the last modified date of the source and 
include files. Column position synchronization information is provided 
whenever macro substitution takes place. The line 'this is a line', where 'is' is a 
macro defined to be 'was', would generate the output 'this A Awas A Bis A C a 
line'. The three control characters are used to delimit the new and old strings. 
Consumers of the output can use this information to determine actual source 
file column positions. The original characters reflect the state of the input line 
after trigraphs are substituted, continuation lines are catenated, and comments 
are removed. Use of these constructs preceding functional code on a line 
makes the column information inaccurate. Use of -C avoids this problem for 
comments. 

-w 

Prevents cpp8086 from generating warnings. 

Five special names are understood by cpp8086. They can be used anywhere 
(including in macros) just as any other defined name. 

LINE is defined as the current line number (as a decimal integer) as known by 
cpp8086. 

FILE is defined as the current file name (as a C string) as known by cpp8086. 
DATE is defined as the current date (as a C string) of the form "Mmm dd yyyy". 
TIME is defined as the current time (as a C string) of the form "hh:mm:ss". 
STDC is defined as 1 indicating an ANSI standard C compiler. 
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All cpp8086 directives start with lines begun by # . Any number of blanks and 
tabs are allowed before and after the # . The directives are: 

# define "name" ""token-string Replace subsequent instances of name with 
token-string, (token-string may 'be null). 

# define name( org, arg) token-string Notice that there can be no space 
between name and the (. Replace subsequent instances of namefarg, arg) by 
token-string, where each occurrence of an arg in the token-string is replaced by 
the corresponding set of tokens in the comma-separated list. When a macro 
with arguments is expanded, the arguments are placed into the expanded 
token-string after they have been recursively macro substituted. After the 
entire token-string has been expanded, cpp8086 re-starts its scan for names to 
expand at the beginning of the newly created token-string. Any name which was 
expanded in a nested macro invocation is not available for expansion until the 
end of the parent macro. 

The # operator in the replacement token-string is a "stringization" unary 
operator causing the parameter name following it to become a C string literal 
containing the substituted argument. For example: 

# define stringize(a) # a 
stringize(This will be a "string"An) 

becomes: 

"This will be Y'stringY'An" 

The # # operator in the replacement token-string is a concatenation operator 
which allows the user to substitute for a portion of an identifier, operator, or 
other token by placing the # # between the parameter and the remainder of 
the token. First the parameter is substituted and then the # # and any white 
space surrounding it are removed. For example: 

# define f(x) var # # x 
f(3) 

results in: 
var3 

# undef "name" 

Cause the definition of name (if any) to be forgotten from now on. 
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# include "filename" 

# include < filename> 

# include token-string 

Include at this point the contents of filename (which is then run through 
cpp8086). If the # include doesn't match one of the first two forms then the 
token-string is macro substituted and retried to see if it matches one of the first 
two forms. See the -I option above for more detail. 

# line integer-constant "filename" 

Causes cpp8086 to generate line control information for the next pass of the C 
compiler. Integer-constant is the line number of the next line and filename is 
the file where it comes from. If "filename" 'is not given, the current file name is 
unchanged. 

# endif 

Ends a section of lines begun by a test directive (# if, # ifdef, or # ifhdef). Each 
test directive must have a matching # endif. 

# ifdef "name" 

The lines following will appear in the output if and only if name has been the 
subject of a previous # define without being the subject of an intervening 

# undef. 

# ifndef "name" 

The lines following will not appear in the output if and only if name has been 
the subject of a previous # define without being the subject of an intervening 

# undef. 

# if "constant-expression" 

Lines following will appear in the output if and only if the constant-expression 
evaluates to non-zero. All binary non-assignment C operators, the ?: 
operator, the unary -, !, and ~ operators are all legal in constant-expression. 
The precedence of the operators is the same as defined by the C language. 
There is also a unary operator defined, which can be used in 
constant-expression in these two forms: defined ( name ) or defined name. This 
allows the utility of # ifdef and # ifndef in a # if directive. Only these 
operators, integer constants, and names which are known by cpp8086 should 
be used in constant-expression. In particular, the sizeof operator is not 
available. 

# elif "constant-expression" 

Any number of # elif directives can occur between one of the test directives 
and the matching # endif. If none of the preceding test or # elif directives have 
been true and this constant-expression evaluates to true then the following 



390 



Chapter 17: On-line Manual Pages 

cpp8086(1) 



lines will appear in the output. The constant-expression is evaluated the same 
as in the # if directive. 

# else 

Can occur after a test directive and any intervening # elif directives and before 
the matching # endif directive. If none of the preceding tests have been true 
then the following lines will appear in the output. 

# pragma 

All lines with the # pragma directive are passed unchanged to the output 
except for removal of leading whitespace. 

# error "token-string" 

Write a diagnostic message to stderr. The preprocessor will continue 
processing after this directive is encountered, but cc8086 will not continue the 
compilation process. The # error directive is useful for debugging # if and 

# ifdef directives. 

The test directives and the possible # elif and # else directives can be nested. 
The cpp8086 command supports names up to 255 characters in length. 

FILES /usr/hp64000/include/8086 directory for standard # include files. 

AUTHOR The cpp8086 command was developed by the Hewlett-Packard Company. 

SEE ALSO cc8086(l),m4(l) 

B. W. Kernighan and D. M. Ritchie, The C Programming Language, Second 
Edition, Prentice-Hall, 1988 

HP 8086/186 C Cross Compiler User's Guide, Hewlett-Packard, 1995 

DIAGNOSTICS The error messages produced by cpp8086 are intended to be self-explanatory. 

The line number and filename where the error occurred are printed along with 
the diagnostic. 

NOTES When new-line characters are found in argument lists for macros to be 

expanded, the current version of cpp8086 replaces these new-lines with blanks. 
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clst8086(1) 

NAME clst8086 - Listing generator for the 8086 C cross compiler 

SYNOPSIS /usi7hp64000/lib/clst8086 [ options ] outputfile 

DESCRIPTION The clst8086 program is the listing generator of the C cross-compiler for the 

Intel 8086 microprocessor. It generates a listing in outputfile (stdout, if -o 
present) from the assembly source or listing file read from stdin. The lister's 
ability to include C source file lines is driven by ?file, ?line, and "*LINE*" 
directives in the assembly code. The preferred way to invoke clst8086 is 
through the cc8086{\) command, since the functionality may someday be 
moved elsewhere. Therefore, the use of clst8086 other than in this framework 
is not suggested. 

The default listing produced contains C source lines with line numbers and 
interleaved assembly code (except special ?directives, see -d below). C include 
files are not expanded, and no cross reference is listed. The contents of listings 
generated vary with the following options: 

The first two options support options of cc8086{\). 

-i 

Add C source included via # include C pre-processor directives, 
-x 

Add cross reference of symbols in C source and any expanded include files. 

The following remaining options are not directly used by cc8086{\), but may 
be used via cc8086(l)'s -W option or by invoking the lister directly. 

-a 

Delete assembly source lines (possibly with associated program counter and 
object code values). 

-c 

Suppress the C source lines. This results in, essentially, an assembler listing or 
source file. 
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-d 

Do not omit assembly source lines containing "?pseudo-operations". 
-H header 

Cause header io be used as the first line generated on each page of the listing, 
-o 

Override the output file specified and write the listing to stdout. This maybe 
used, via -W, to cause cc8086(l) to produce listings to stdout. 

-t 

Surround C source statements with HP terminal "inverse video on" (i.e. esc & 
d B) and "inverse video off (i.e. esc & d @) escape sequences for convenient 
terminal viewing. This is particularly handy when viewing lister output with 
the more(l) command; it is not too handy when viewing lister output with the 
vz'(l) command. 

Note that options other than the above are not recognized and cause a 
warning message to be written to stderr. 

AUTHOR Clst8086 was developed by the Hewlett-Packard Company. 

SEE ALSO as86(l),cc8086(l) 

HP 8086/186 C Cross Compiler User's Guide, Hewlett-Packard, 1995 
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* (indirection operator) 

See pointers, dereferencing 
80186 support, 43, 142 
8087 

See floating point coprocessor 
_error_msg, 319 

abort (standard C function), 145 
abs (math library function), 157 

access 

See segment relative access 
accessing on-line command descriptions, note on, 36 
acos (math library function), 216-217 
ADD_F32A addition routine, 297 
ADD_F32B addition routine, 298 
ADD_F32C addition routine, 298 
ADD_F64A addition routine, 295 
ADD_F64B addition routine, 296 
ADD_F64C addition routine, 296 
ALIAS pragma, 71 

See the on-line man page 
alignment considerations, internal data, 64-66 
ANSI standard, 46-52 

embedded assembly language, 92 
ar86 librarian, 45 
arguments 

optional, 228-229 
arithmetic data types, internal data representation, 54-57 
array 

of pointers to functions, 267 
arrays 

alignment, 64, 66 

initializing with strings, 60 

internal data representation, 59 
as86 assembler, 45 

asin (math library function), 216-217 
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asm () function, 97, 102 

ASM pragma, 93 

assembler (as86) and C compilation, 45 
assembly language, 67-104 

in the C source file, 92-104 

memory model independent code, 103 

symbol names, 69-71 

with small model, 102 
assembly preprocessor, 45 
assert (support library function), 158 
assert.h, include file, 146 
assignment compatibility, 46 

between pointer and integers, 46 

between pointer and pointers, 46 
atan, atan2 (math library function), 216-217 
atexit (support library function), 159 
atof (support library function), 223 
atoi, atol (support library function), 224-225 
auto variables, 12 
auto, storage class specifier, 111 
AxLS (Advanced Cross Language System), 39-52 

B behavior of exit and _exit when using crtl, 235 
behavior of math library functions, 329 
binary search, bsearch routine, 160-161 
bit fields, internal data representation, 62 
branch shortening (peephole optimization), 116, 118 
bsearch (standard library function), 160-161 
buffering of output streams, 199 
bufsiz, macro defining I/O buffer size, 242 
bus width, 338 

C C compilation overview, 39-52 
C compiler (ccom8086) 

See the on-line man pages 
C compiler (ccom8086L, ccom8086S), 44 
C language 

ANSI extensions, 46-52 

translation limits, 51 
C preprocessor (cpp8086), 44 
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C/64000 comparison 

general options, 338-341 

processor specific options, 342-343 
calling conventions (stack frame management), 72-86 
calling libraries 

See libraries 
calloc (support library function), 187-188 
casts, 46, 160, 175, 202 
cc8086 

option summary, 4-5 
cc8086 (compilation control routine), 44 

See also the on-line man pages 
ccom8086 C compiler, 44 
ceil (math library function), 168 
character data types, 57 
characters, multi-byte, 185 
checking for memory model mismatch, 90-91 
_clear_fp_status (math library function), 171-174 
clear_screen (env. dependent library function), 243 
clearerr (standard I/O library function), 165 
close (environment-dependent library function), 244 
clst8086 lister, 45 
coalescing (optimization), 111 
CODE class name, 127 
command-line options, 369 
compact memory model, 124-126 
compilation control routine (cc8086), 44 
compilation control routine (cc8086, cc80186), 44 
compiler features, iv 

compiler generated assembly code, 67-104 
compiler generated symbols, 71 
config.EA, emulator configuration file, 236 
configuration files for HP emulators, 236 
const type modifier, 50 
const, default constant segment name, 127 
constant folding (optimization), 107 
constants 

string, 60 
constants, multi-character, 57 
constants, string, 111 
constants, where to load, 133 



cos (math library function), 216-217 
cosh (math library function), 218 
cpp8086 C preprocessor, 44 
crtO program setup routine, 235 
crtO.o file, 16 

crtl program setup routine, 235 

behavior of exit and _exit when using, 235 
ctype.h, include file, 146 

??DATA segment, 133 

data bus width, 338 

data motion optimizations, 118 

data types 

arithmetic, 54-57 

character, 57 

derived, 58-63 

floating-point, 54 

integral, 54 

volatile modifier, 136-137 
data, default data segment name, 127 
data_const, 103 

debug code, maintaining despite optimization, 115 

debug directives, 72 

debug error messages (run-time), 279 

DEC_F32 subtraction routine, 303 

DEC_F64 subtraction routine, 301 

default linker command file, iolinkcom.k, 236 

default modes of operation in the 8087 and 8086 libraries, 172 

default PROG names, small and large memory model, 127 

denormal number, 279 

denormalized operand, trap on, 173 

dependencies, execution environment, 40 

dereferencing 

See pointers, dereferencing 
dereferencing, definition of, 90 

derived data types, internal data representation, 58-63 
diagnostics, assert macro, 158 

display_message (display run-time error messages), 236 
div (math library function), 162 
DIV_F32A division routine, 308 
DIV_F32B division routine, 309 
DIV_F32C division routine, 309 



DIV_F64A division routine, 307 

DIV_F64B division routine, 307 

DIV_F64C division routine, 308 

DIV_I32A division routine, 316 

DIV_I32B division routine, 316 

div_t type (defined in stdlib.h), 147 

DIV_UI32A division routine, 315 

DIVJJI32B division routine, 315 

divide by zero, trapping on, 172 

double data type, examples of, 56 

double -precision (IEEE) floating-point format, 56 

DS pragma, 131 

dynamic allocation, 241 

embedded assembly language 

in C source, 92-104 

memory model independent, 103 

small model, 102 
embedded systems considerations, 121 
emulator configuration files, 236 
END_ASM pragma, 93 

enumeration types, internal data representation, 63 
env, segment name of environment-dependent routines, 234 
env.a, environment-dependent library, 242 
environment, 35 

environment-dependent libraries, modifying, 33-35 
environment-dependent routines, 40, 122, 145, 233-264 
EQUAL_F32 comparison routine, 311 
EQUAL_F64 comparison routine, 310 
errno (support library function), 146, 192 
errors 

compile-time, 265-276 

multiple declarations, 127 

run-time, 277-282 
escape sequences, 60 
example 

calling run-time and support libraries, 25 

using large memory model, 12 
examples, alignment, 66 
exceptions history, loss of, 79 

exec_cmd (env. dependent library function), 245-246 



execution environment, 35 

See also libraries 
execution environment dependencies, 40 
execution environments, 122 
exit and _exit, how crtl affects behavior, 235, 247 
exit, _exit (env. dependent library function), 247 
exp (math library function), 163 
exponent field, 55 
expressions 

constant folding across, 108 

in a logical context (optimization), 110 

simplification (optimization), 108 
extended character set, 57 
extensions (ANSI) to C, 46-52 
extensions, file name, 6 
extern definitions, 129 
external declarations, 47, 70 

placement of, 134-135 

static, 131 

warning about, 275 

warning about NEAR calls, 275 
external declarations, segment name check, 127 
external definitions, 130 
external identifiers 

length of, 51 
external references, 46 

F32_TO_F64 conversion routine, 286 
F32_TO_I16 conversion routine, 294 
F32_TO_I32 conversion routine, 293 
F32_TO_UI16 conversion routine, 292 
F32_TO_UI32 conversion routine, 291 
F64_TO_F32 conversion routine, 286 
F64_TO_I16 conversion routine, 290 
F64_TO_I32 conversion routine, 289 
F64_TO_UI16 conversion routine, 288 
F64_TO_UI32 conversion routine, 287 
fabs (math library function), 168 
FAR functions, 125 
FAULT_I16 fault routine, 324 
FAULT_I32 fault routine, 323 
FAULT_I8 fault routine, 325 



FAULT_PTR fault routine, 319 

FAULT_UI16 fault routine, 321 

FAULT_UI32 fault routine, 320 

FAULTJJI8 fault routine, 322 

fclose (standard I/O library function), 164 

features of the compiler, iv 

ferror, feof (standard I/O library function), 165 

fflush (standard I/O library function), 164 

fgetc (standard I/O library function), 177 

fgetpos (standard I/O library function), 166-167 

fgets (standard I/O library function), 178 

fields in floating-point data types, 54 

file extensions, 6 

file names 

extensions, 6 
file output, 199 
files 

emulator configuration, 236 

include (header), 142, 146 

library, 142 

linker command, 236 

program setup routines (crtO, crtl), 235 
float data type, examples of, 55 
float.h, include file, 146 
floating point coprocessor, 171-174 
floating point coprocessor (8087), 56, 79, 142, 279 

control word, 173 

precision of real number operations, 56 

registers, 89 
floating-point data types, 54 
floating-point error functions, 146 
floating-point error messages (run-time), 278 
floating-point formats (single- and double -precision), 55 
floor (math library function), 168 
fmod (math library function), 168 
fopen (standard I/O library function), 169-170 
fopen_max macro (max. number of I/O control blocks), 242 
fp_control.h, include file, 146, 171 
_fp_error (math library function), 171-174 
fprintf (standard I/O library function), 194-198 
fputc (standard I/O library function), 199-200 



fputs (standard I/O library function), 201 
fraction field, 55 

frame pointer, offset of parameters, 79 
frame pointer, stack frame management, 78 
fread (standard I/O library function), 175 
free (support library function), 187-188 
frem (math library function), 168 
freopen (standard I/O library function), 169-170 
frexp (support library function), 176 
fscanf, 205-209 

fseek (standard I/O library function), 166-167 
fsetpos (standard I/O library function), 166-167 
ftell (standard I/O library function), 166-167 
function entry and exit, 118 
function prototypes 

example, 47 

how to use, 47 

parameter passing example, 80 
FUNCTION_ENTRY pragma, 99 
FUNCTION_EXIT pragma, 99 
FUNCTION_RETURN pragma, 99 
functions 

array of pointers to, 267 

calls, 72 

data passing, 88 

exit, 85 

FAR calls, 125 

implementing as interrupt routines, 139 
prolog, 79 
results, 85 

return value on stack, 78 
fwrite (standard I/O library function), 175 

generate code for 8087 (command line option) 
precision of operations, 56, 173 
precision of real number operations, 56 
register usage, 87-89 

generate debug code (command line option), 115 

generate run-time error checking, 90 

generic pointers, 49 

_get_fp_control (math library function), 171-174 
_get_fp_status (math library function), 171-174 
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getc, getchar (standard I/O library function), 177 

getenv (standard C function), 145 

_getmem (env. dependent library function), 241 

rewriting, 241 
getmem (env. dependent library function), 248-249 
gets (standard I/O library function), 178 
getting started, 1-36 
groups, 125 
GRP macro, 103 

H header files, 146 

memory.h, 248, 260 
simio.h, 242 
hex escape sequences, 60 
hooks for execution environment, 35 
HP-UX commands, 2 

I I/O, eliminating, 140 

I16_TO_F32 conversion routine, 294 
I16_TO_F64 conversion routine, 290 
I32_TO_F32 conversion routine, 293 
I32_TO_F64 conversion routine, 289 
INC_F32 addition routine, 299 
INC_F64 addition routine, 297 
include files, 130, 146 

conflict with SECTION pragma, 130 

memory.h, 248, 260 

simio.h, 242 
inexact result, trapping on, 172 
infinity, controlling 8087 behavior, 173 
??INIT segment class, 133 

_init_fp (support library function for 8087), 172 
initdata, 133 
initializing arrays, 60 

initsimio (env. dependent library function), 250 
input and output, 242 
installation, 7 

integers, assignment compatibility, 46 
integral data types, 54, 146 
internal data representation, 53-66 
INTERRUPT pragma, 139 
See also pragmas 
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interrupt routines 

implementing functions as, 139 

stack models, 354 
interrupt routines and the 8087, 79 
ioconfig.EA, emulator configuration file, 236 
iolinkcom.k 

default linker command file, 236 
isalnum (support library function), 179-180 
isalpha (support library function), 179-180 
iscntrl (support library function), 179-180 
isdigit (support library function), 179-180 
isgraph (support library function), 179-180 
islower (support library function), 179-180 
isprint (support library function), 179-180 
ispunct (support library function), 179-180 
isspace (support library function), 179-180 
isupper (support library function), 179-180 
isxdigit (support library function), 179-180 

J jmp_buf type (defined in setjmp.h), 146 
jump shortening 

See branch shortening 

K kill (environment-dependent library function), 251 

L l_tmpnam, standard C definition, 145 
labs (math library function), 157 
large and small memory mismatch, link time, 90-91 
large memory model, 124-126 

See memory model 

segment name defaults, 127 
ld86 linker/loader, 46 
ldexp (support library function), 176 
ldiv (math library function), 162 
ldiv_t type (defined in stdlib.h), 147 
LESS_EQ_F32 comparison routine, 313 
LESS_EQ_F64 comparison routine, 312 
LESS_F32 comparison routine, 312 
LESS_F64 comparison routine, 311 
librarian, C compilation overview, 45 



404 



libraries, 141-232 

calling run-time and support, 25 

default modes of operation in the 8087 and 8086, 172 

environment-dependent library files, 34 

environment-dependent segment name, 234 

list of all routines, 148 

math, 56 

nonreentrant routines, 138 
purpose of environment libraries, 35 
routine names, 144 
run-time, 56, 144 
support, 145 

support routines not provided, 145 
limits, translation, 51 
limits.h, include file, 146 
linkcom.k, linker command file (no I/O), 236 
linker (ld86) and C compilation, 46 
linker command file (default), iolinkcom.k, 236 
lister (clst8086), 45 
listing generated, 12, 17, 19, 22 
literals, string, 111 

loading constants, where to load, 133 

local variables, how the compiler allocates stack space for, 78 
locale.h, include file, 146 

localeconv (support library function), 181-185 
locals, how the compiler accesses, 85 
log, loglO (math library function), 186 
longjmp (support library function), 212-213 
loop construct optimization, 110 
loss of precision, trapping on, 172 

lseek (environment-dependent library function), 252-253 
macros 

embedding assembly language, 102 
make utility, 33-34 
makefiles, using with cc8086, 30-32 
malloc (support library function), 187-188 
man, on-line command descriptions, 36, 369 
map memory model, 238 
mass storage initialization of RAM data, 132 



math library, 145 

behavior of functions, 329 

descriptions, 156 
math.h, include file, 146 
MB_CUR_MAX macro, 185 
mblen (support library function), 189-190 
mbstowcs (support library function), 189-190 
mbtowc (support library function), 189-190 
memchr (support library function), 191 
memcmp (support library function), 191 
memcpy (support library function), 191 
memmove (support library function), 191 
memory access (forced by volatile), 136-137 
memory model, 34 

discussion of, 124-126 

example using large memory model, 12 

independent assembly code, 103 

library dependencies, 142, 284 

map, 238 

mismatch checking, 90-91, 142 

segment name defaults, 127 

selection, 11-27 

small, 16, 19, 22 

stack usage, 354 
memory.h, include file, 248, 260 
memset (support library function), 191 
"mixing extern declaration ..." warning, 275 
MOD_I32A modulo routine, 318 
MOD_I32B modulo routine, 318 
MODJJI32A modulo routine, 317 
MODJJI32B modulo routine, 317 

modes of operation in the 8087 and 8086 libraries, default, 172 
modf (support library function), 176 
mon_stub.o file, 33 

MUL_F32A multiplication routine, 305 
MUL_F32B multiplication routine, 306 
MUL_F32C multiplication routine, 306 
MUL_F64A multiplication routine, 304 
MUL_F64B multiplication routine, 304 
MUL_F64C multiplication routine, 305 
MUL_I32A multiplication routine, 314 
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MUL_I32B multiplication routine, 314 
multi-byte characters, 185 
multi-character constants, 57 

multiple symbol declarations, segment name check, 127 

N names 

See symbol names 
NaN, 55 

near stack model, 354 
nil pointers 

See null pointers 
no initialized RAM data, 131 
nonreentrant library routines, 138 
normalized numbers, 55 
Not a Number (NaN), 55 
note on 

accessing on-line command descriptions, 36 
notes 

changing string constants, 60, 112 
environment-dependent library functions, 156 
nested SEGMENT-SEGMENT UNDO pairs, 130 
universal optimizations examples, 106 
NPX 

See floating point coprocessor 
NULL character 

in initialized arrays, 60 

in strings, 60 
null pointers, 90, 279 

O on-line command descriptions (HP-UX man command), 36 
open (environment-dependent library function), 254-256 
operand error, trapping on, 172 

operating modes in the 8087 and 8086 libraries, default, 172 

operating system commands, 2 

operation simplification (optimization), 109 

opt8086 peephole optimizer, 44 

optimizations, 105-120 

automatic allocation of register variables, 111 

constant folding, 107 

expression simplification, 108 

expressions in a logical context, 110 

function entry and exit, 118 
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optimizations (cont) 
loop construct, 110 
maintaining debug code during, 115 
operation simplification, 109 
switch statement, 111 

those activated with the command line option, 114-120 
time vs. space, 115 

universal (always performed), 106-113 

See also peephole optimizations 
option summary, 4-5 
options, detailed descriptions, 369 
order of evaluation, maintaining, 108 
overflow, trapping on, 172 
overview of C compilation, 39-52 

padding 

internal data representation, 64 

structures, 61 
parameters, 12 

how the compiler accesses, 79 

passing of (stack frame management), 77 

shortening of, 80 

widening of, 47, 65, 77 
parentheses, 108 
peephole optimizations, 116-118 

branch shortening, 116 

branch shortening/simplification optimizations, 118 

data motion optimizations, 118 

effect of volatile data on, 118 

redundant jump elimination, 117 

redundant register load elimination, 117 

strength reduction, 117 

tail merging, 116 

unreachable code elimination, 117 
peephole optimizer (opt8086), 44 
perror (standard I/O library function), 192 
pointers 

assignment compatibility, 46 

dereferencing, 90, 271 

subtraction, 125 

void, 46 

pos_cursor (env. dependent library function), 257 
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pow (math library function), 193 
pragmas, 16, 19, 22, 48 
ALIAS, 71 

ASM and END_ASM, 93 
DS, 103, 131 

FUNCTION_ENTRY, 99 

FUNCTION_EXIT, 99 

FUNCTION_RETURN, 99 

INTERRUPT, 102, 139 

See also names of specific pragmas 

SEGMENT, 103, 128, 131 

See the on-line man pages 
precision of real number operations, 56, 173, 279 
prefixes for assembly language symbols, 69-71 
preprocessor 
C,44 

assembly, 45 

C, 102 
preprocessor directives 

See pragmas 
printf (standard I/O library function), 194-198 
prog, default small model PROG name, 127 
prog_basename, default large model PROG names, 127 
program setup routines, 235 

differences between crtO and crt 1 , 235 

linking the, 236 
PROM programming, 338 
prototypes 

See function prototypes 
ptrdiff_t type (defined in stddef.h), 147 
putc, putchar (standard I/O library function), 199-200 
puts (standard I/O library function), 201 

Q qsort (support library function), 202 

R RAM and ROM considerations, 131-133 

RAM and ROM for Small Memory Model, 133 

RAM data initialized from mass storage, 132 

RAM data initialized from ROM, 133 

RAM data, no initialization, 131 

rand (support library function), 203 

read (environment-dependent library function), 258-259 
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real number operations, precision of, 56, 173 
realloc (support library function), 187-188 
redeclaration of extern as static, 275 

redundant jump elimination (peephole optimization), 117 
redundant register load elim. (peephole optimization), 117 
reentrant code, 138 

functions returning structures, 77 
register usage, 87-89 

buffering(8087 registers), 79 
register variables 

automatic allocation (optimization), 111 

buffering (SI), 79 

reserved registers, 89 
register, storage class specifier, 111 
relocatable segments, 127-130 
remove (support library function), 204 
rename (standard C function), 145 
reseting the 8087, 79 
return values, 77 

rewind (standard I/O library function), 166-167 
ROM and RAM for Small Memory Model, 133 
rounding, and the 8087, 173 
run-time error checking, generating code for, 90 
run-time libraries 

See libraries 
run-time library, 144 

See also libraries 

precision of real number operations, 56 

sbrk (environment-dependent library function), 260 
sbrk, operating system library function, 241 
scanf (standard I/O library function), 205-209 
scope 

assembler naming, 70 
segment names, 127-130 

changing default, 131 

defaults for large memory model, 127 

defaults for memory models, 127 

defaults for small memory model, 128 

environment-dependent routines (env), 234 

external data, 127 

multiple declarations of the same symbol, 127 



SEGMENT pragma, 16, 19, 22, 128 

segment relative access, 12 

SEGMENT-SEGMENT UNDO pairs, note on nested, 130 

_set_fp_control (math library function), 171-174 

setbuf, setvbuf (standard I/O library function), 210-211 

setjmp (support library function), 212-213 

setjmp.h, include file, 146 

setlocale (support library function), 214-215 

shortening of parameters, 80 

side effects, 102, 112 

sign bit field, 54 

signal.h, standard include file, 145 
signed integral data types, 54 
simio.h, include file, 242 

simple example program, compiling and executing, 9 

sin (math library function), 216-217 

single -precision (IEEE) floating-point format, 55 

sinh (math library function), 218 

size_t type (defined in stddef.h), 147 

small and large memory model mismatch, link time, 90-91 
small memory model, 124-126 

and assembly language, 102 

See memory model 

RAM and ROM, 133 

segment name defaults, 128 
sprintf (standard I/O library function), 194-198 
sqrt (math library function), 219 
srand (support library function), 203 
sscanf (standard I/O library function), 205 
stack frame management, 72-86 
stack models, 354 
stack pointer, 8087, 89 
standards 

See ANSI standard 
startup error messages (run-time), 281 
startup, library routine called by crtO, 235 
static variables, 70 

accidental redeclaration, 275 

const, 50 

initialized arrays, 60 
stdarg.h, include file, 146 



stddef.h, include file, 147 
stdin, stdout, stderr streams, 235 
stdio.li 

definitions and functions not provided, 145 

include file, 147 
stdlib.h 

functions not supported, 145 

include file, 147 
strcat (support library function), 220-222 
strchr (support library function), 220-222 
strcmp (support library function), 220-222 
strcoll (support library function), 220-222 
strcpy (support library function), 220-222 
strcspn (support library function), 220-222 
streams 

buffered binary I/O to, 175 

closing and flushing, 164 

EOF, 200 

failure to close, 211 

file buffering, 210 

formatted print to, 194 

formatted read from, 205 

opening, 169 

print string to, 201 

printing character to, 199 

push character back, 227 

reading characters, 177 

standard error, 199 

status inquiries, 165 
strength reduction (peephole optimization), 117 
strerror (support library function), 220-222 
string.h, include file, 147 
strings 

and character pointers, 112 
coalescing (optimization), 111 
constant, 60 

constants, optimization, 111 
definition, 60 
escape sequences, 60 
initializing an array, 60 



strings (cont) 
literals, 129 

literals in CONST segment, 127 

printing to a string, 194, 230-232 

side effects, 112 
strip symbol table information option, 72 
strlen (support library function), 220-222 
strncat (support library function), 220-222 
strncmp (support library function), 220-222 
strncpy (support library function), 220-222 
strpbrk (support library function), 220-222 
strrchr (support library function), 220-222 
strspn (support library function), 220-222 
strstr (support library function), 220-222 
strtod (support library function), 223 
strtok (support library function), 220-222 
strtol, strtoul (support library function), 224-225 
structure results, 72, 77 
structures 

internal data representation, 61 

size of, 61 

strxfrm (support library function), 189-190 
SUB_F32A subtraction routine, 302 
SUB_F32B subtraction routine, 302 
SUB_F32C subtraction routine, 303 
SUB_F64A subtraction routine, 300 
SUB_F64B subtraction routine, 300 
SUB_F64C subtraction routine, 301 
summary of cc8086 options, 4-5 
support libraries 

See libraries 
support library, 145 

descriptions, 156 

routines not provided, 145 
switch statement optimization, 111 
symbol names 

assembly language, 69-71 

parameters, 79 

situations where C symbols are modified, 70 
system (standard C function), 145 
systemio, environment dependent I/O functions, 242 
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T table 

binary search routine, 160-161 

character classification, 179 

sort routine, 202 
tail merging (peephole optimization), 116 
tan (math library function), 216-217 
tanh (math library function), 218 
temporary storage, use of the stack, 85 
time vs. space optimization, 115 
time.h, standard include file, 145 
tmp_max, standard C definition, 145 
tmpfile (standard C function), 145 
tmpnam (standard C function), 145 
tolower, _tolower (support library function), 226 
toupper, _toupper (support library function), 226 
translation limits, 51 
traps, 172 
types 

See data types 

U UDATA SEGMENT, 275 

UI16_TO_F32 conversion routine, 292 
UI16_TO_F64 conversion routine, 288 
UI32_TO_F32 conversion routine, 291 
UI32_TO_F64 conversion routine, 287 
unary plus (+ ) operator, 108 
underflow, trapping on, 172 
undo, form of the segment pragma, 130 
ungetc (standard I/O library function), 227 
uninitialized data option, 132 
unions 

internal data representations, 63 
size of, 58 

unlink (environment-dependent library function), 261-262 
unreachable code elimination (peephole optimization), 117 
user-defined option (C/64000 only), 342 

V va_arg, va_end, and va_start macros, 146 
vajist, 228-229 

va_list type (defined in stdarg.h), 146 
variable argument lists, 228-229 
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variable names, 70 

symbol names, 69-71 
vector address, functions as interrupt routines, 139 
void type, 49 

assignment compatibility of pointers, 47 
volatile type modifier, 49, 136-137 

effect on peephole optimizations, 118 
vprintf, vfprintf, vsprintf (std. I/O library function), 230-232 

warnings, compile-time, 274 

uninitialized data, 132 
wchar_t type (defined in stddef.h), 57, 147 
wcstombs (support library function), 189-190 
wctomb (support library function), 189-190 
white space, 102 
wide characters, 57 
widening of parameters, 47, 77, 80 

write (environment-dependent library function), 263-264 
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Certification and Warranty 



Certification 

Hewlett-Packard Company certifies that this product met its published 
specifications at the time of shipment from the factory. Hewlett-Packard 
further certifies that its calibration measurements are traceable to the United 
States National Bureau of Standards, to the extent allowed by the Bureau's 
calibration facility, and to the calibration facilities of other International 
Standards Organization members. 



Warranty 

This Hewlett-Packard system product is warranted against defects in materials 
and workmanship for a period of 90 days from date of installation. During the 
warranty period, HP will, at its option, either repair or replace products which 
prove to be defective. 

Warranty service of this product will be performed at Buyer's facility at no 
charge within HP service travel areas. Outside HP service travel areas, 
warranty service will be performed at Buyer's facility only upon HP's prior 
agreement and Buyer shall pay HP's round trip travel expenses. In all other 
cases, products must be returned to a service facility designated by HP. 



For products returned to HP for warranty service, Buyer shall prepay shipping 
charges to HP and HP shall pay shipping charges to return the product to 
Buyer. However, Buyer shall pay all shipping charges, duties, and taxes for 
products returned to HP from another country. HP warrants that its software 
and firmware designated by HP for use with an instrument will execute its 
programming instructions when properly installed on that instrument. HP 
does not warrant that the operation of the instrument, or software, or 
firmware will be uninterrupted or error free. 

Limitation of Warranty 

The foregoing warranty shall not apply to defects resulting from improper or 
inadequate maintenance by Buyer, Buyer-supplied software or interfacing, 
unauthorized modification or misuse, operation outside of the environment 
specifications for the product, or improper site preparation or maintenance. 

No other warranty is expressed or implied. HP specifically disclaims the 
implied warranties of merchantability and fitness for a particular purpose. 

Exclusive Remedies 

The remedies provided herein are buyer's sole and exclusive remedies. HP 
shall not be liable for any direct, indirect, special, incidental, or consequential 
damages, whether based on contract, tort, or any other legal theory. 

Product maintenance agreements and other customer assistance agreements 
are available for Hewlett-Packard products. 



For any assistance, contact your nearest Hewlett-Packard Sales and Service 
Office. 



